Add a headless combat scenario with a hostile duelist
Ashlar checks / tooling (push) Successful in 6s

SCENARIO=combat docker/ashlar-run.sh loads docker/scenarios/combat on top
of the Game Template: our own CC0 Lua content that gives the player a
shield and blade and spawns a hostile duelist with the same kit, cloned
from the template's player record. The player holds Block, then attacks,
and the run prints block counts. The default boot is unchanged.

The engine now logs each successful shield block or parry at verbose
level ("Ashlar block: ..."), so runs can count them.

Documented in docs/ashlar/SCENARIOS.md.

Closes #24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-14 03:30:23 -05:00
co-authored by Claude Opus 5.5
parent c0bb7e01f7
commit bc600b3359
9 changed files with 295 additions and 1 deletions
+9
View File
@@ -5,6 +5,7 @@
#include <components/esm3/loadarmo.hpp>
#include <components/esm3/loadgmst.hpp>
#include <components/debug/debuglog.hpp>
#include <components/esm3/loadweap.hpp>
#include <components/sceneutil/positionattitudetransform.hpp>
#include <components/settings/values.hpp>
@@ -153,6 +154,14 @@ namespace MWMechanics
if (blocker == getPlayer())
blocker.getClass().skillUsageSucceeded(blocker, ESM::Skill::Block, ESM::Skill::Block_Success);
logBlock(attacker, blocker, "weapon", damageThrough);
return damageThrough;
}
void logBlock(const MWWorld::Ptr& attacker, const MWWorld::Ptr& blocker, const char* kind, float damageThrough)
{
Log(Debug::Verbose) << "Ashlar block: " << blocker.getCellRef().getRefId() << " blocked "
<< attacker.getCellRef().getRefId() << " with " << kind << ", "
<< (isInBlockStance(blocker) ? "stance" : "roll") << ", damage through " << damageThrough;
}
}
+4
View File
@@ -25,6 +25,10 @@ namespace MWMechanics
/// Damage that gets through a weapon block. \a damageTaken is the share that gets through, 0 to 1.
float weaponBlockDamage(float damage, float damageTaken);
/// Writes a verbose log line for a successful block, so headless test scenarios can count blocks. \a kind is
/// "shield" or "weapon".
void logBlock(const MWWorld::Ptr& attacker, const MWWorld::Ptr& blocker, const char* kind, float damageThrough);
/// Signed angle of \a attacker relative to the facing of \a blocker, in degrees. \a blocker needs a base node.
float getAttackAngleDegrees(const MWWorld::Ptr& attacker, const MWWorld::Ptr& blocker);
+1
View File
@@ -180,6 +180,7 @@ namespace MWMechanics
if (blocker == getPlayer())
blocker.getClass().skillUsageSucceeded(blocker, ESM::Skill::Block, ESM::Skill::Block_Success);
logBlock(attacker, blocker, "shield", 0.f);
return true;
}
return false;
+23 -1
View File
@@ -1,11 +1,19 @@
#!/usr/bin/env bash
# Boots the built engine on the asset-free Game Template on a virtual display
# and saves a screenshot. Run docker/ashlar-build.sh first.
#
# SCENARIO=combat also loads docker/scenarios/combat, our own CC0 test content: a hostile duelist with a shield
# and blade fights the player, and block events are summarized at the end. See docs/ashlar/SCENARIOS.md.
set -euo pipefail
repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cache="${ASHLAR_CACHE_DIR:-$HOME/.cache/ashlar}"
boot_seconds="${BOOT_SECONDS:-90}"
scenario="${SCENARIO:-}"
if [ -n "$scenario" ]; then
boot_seconds="${BOOT_SECONDS:-120}"
else
boot_seconds="${BOOT_SECONDS:-90}"
fi
memory="${MEMORY:-6g}"
image="ashlar-build:trixie"
suite="$cache/content/example-suite"
@@ -21,6 +29,13 @@ cat > "$run/home/.config/openmw/openmw.cfg" <<'EOF'
data="/cache/content/example-suite/game_template/data"
content=template.omwgame
EOF
scenario_mount=()
if [ -n "$scenario" ]; then
[ -f "$repo/docker/scenarios/$scenario/ashlar$scenario.omwscripts" ] \
|| { echo "Unknown scenario: $scenario" >&2; exit 1; }
printf 'data="/scenario"\ncontent=ashlar%s.omwscripts\n' "$scenario" >> "$run/home/.config/openmw/openmw.cfg"
scenario_mount=(--volume "$repo/docker/scenarios/$scenario:/scenario:ro")
fi
{
cat "$suite/settings.cfg"
printf '\n[Video]\nresolution x = 1280\nresolution y = 720\nwindow mode = 2\n'
@@ -33,6 +48,7 @@ docker run --rm \
--env DISPLAY=:99 \
--env LIBGL_ALWAYS_SOFTWARE=1 \
--volume "$cache:/cache" \
"${scenario_mount[@]}" \
--workdir /cache/build \
"$image" bash -uc "
Xvfb :99 -screen 0 1280x720x24 +extension GLX >/dev/null 2>&1 &
@@ -53,3 +69,9 @@ docker run --rm \
exit 0
"
echo "Screenshot: $run/boot.png"
if [ -n "$scenario" ]; then
echo "Scenario $scenario:"
grep -E 'ASHLAR_COMBAT|Ashlar block:|scripts/ashlar' "$run/stdout.log" | tail -60 || true
echo "Player blocks: $(grep -ci 'Ashlar block: "player" blocked' "$run/stdout.log" || true)"
echo "NPC blocks: $(grep 'Ashlar block:' "$run/stdout.log" | grep -vci 'Ashlar block: "player" blocked' || true)"
fi
@@ -0,0 +1,3 @@
GLOBAL: scripts/ashlarcombat/global.lua
PLAYER: scripts/ashlarcombat/player.lua
CUSTOM: scripts/ashlarcombat/npc.lua
@@ -0,0 +1,58 @@
-- Ashlar headless combat scenario (CC0). Gives the player a shield and a blade, spawns a hostile duelist with the
-- same kit in front of the player, and hands both off to their local scripts. Uses only Game Template meshes.
local world = require('openmw.world')
local types = require('openmw.types')
local util = require('openmw.util')
local started = false
local function log(...)
print('ASHLAR_COMBAT', ...)
end
local function makeKit()
local shieldRec = world.createRecord(types.Armor.createRecordDraft {
name = 'Test Shield', type = types.Armor.TYPE.Shield, weight = 5, value = 1, health = 5000,
baseArmor = 5, enchantCapacity = 0, model = 'meshes/marker_error.dae', icon = '' })
local bladeRec = world.createRecord(types.Weapon.createRecordDraft {
name = 'Test Blade', type = types.Weapon.TYPE.ShortBladeOneHand, weight = 3, value = 1, health = 5000,
speed = 1, reach = 1, enchantCapacity = 0, chopMinDamage = 2, chopMaxDamage = 4, slashMinDamage = 2,
slashMaxDamage = 4, thrustMinDamage = 2, thrustMaxDamage = 4, model = 'meshes/marker_error.dae', icon = '' })
return world.createObject(shieldRec.id), world.createObject(bladeRec.id)
end
local function start(player)
local npcRec = world.createRecord(types.NPC.createRecordDraft {
template = types.NPC.record(player), name = 'Test Duelist', isEssential = false })
local npc = world.createObject(npcRec.id)
local yaw = player.rotation:getYaw()
local forward = util.vector3(math.sin(yaw), math.cos(yaw), 0)
npc:teleport(player.cell, player.position + forward * 160, util.transform.rotateZ(yaw + math.pi))
npc:addScript('scripts/ashlarcombat/npc.lua')
local pShield, pBlade = makeKit()
pShield:moveInto(types.Actor.inventory(player))
pBlade:moveInto(types.Actor.inventory(player))
local nShield, nBlade = makeKit()
nShield:moveInto(types.Actor.inventory(npc))
nBlade:moveInto(types.Actor.inventory(npc))
player:sendEvent('AshlarCombatStart', { shield = pShield, blade = pBlade, enemy = npc })
npc:sendEvent('AshlarCombatStart', { shield = nShield, blade = nBlade, enemy = player })
log('spawned', npc.recordId)
end
return {
engineHandlers = {
onUpdate = function()
if started then
return
end
local player = world.players[1]
if player and player.cell then
started = true
start(player)
end
end,
},
}
@@ -0,0 +1,38 @@
-- Ashlar headless combat scenario (CC0): the duelist equips its kit and fights the player with normal combat AI.
local self = require('openmw.self')
local types = require('openmw.types')
local I = require('openmw.interfaces')
local Actor = types.Actor
-- Stats can only be changed by the actor's own local script.
local function toughen(actor)
local stats = types.Actor.stats
for _, name in ipairs({ 'health', 'fatigue' }) do
local stat = stats.dynamic[name](actor)
stat.base = 5000
stat.current = 5000
end
stats.attributes.agility(actor).base = 100
stats.attributes.strength(actor).base = 60
types.NPC.stats.skills.block(actor).base = 100
types.NPC.stats.skills.shortblade(actor).base = 100
end
I.Combat.addOnHitHandler(function(attack)
local health = attack.damage and attack.damage.health or 0
print(string.format('ASHLAR_COMBAT npc hit successful=%s health=%.2f', tostring(attack.successful), health))
end)
return {
eventHandlers = {
AshlarCombatStart = function(data)
toughen(self)
local eq = Actor.getEquipment(self)
eq[Actor.EQUIPMENT_SLOT.CarriedLeft] = data.shield
eq[Actor.EQUIPMENT_SLOT.CarriedRight] = data.blade
Actor.setEquipment(self, eq)
I.AI.startPackage({ type = 'Combat', target = data.enemy })
print('ASHLAR_COMBAT npc ready')
end,
},
}
@@ -0,0 +1,103 @@
-- Ashlar headless combat scenario (CC0): the player faces the duelist, holds Block for a while so the duelist's
-- attacks hit the shield, then attacks repeatedly so the duelist's AI gets to block.
local self = require('openmw.self')
local types = require('openmw.types')
local util = require('openmw.util')
local I = require('openmw.interfaces')
local Actor = types.Actor
local BLOCK_UNTIL = 14
local ATTACK_UNTIL = 40
local kit
local t = 0
local phase = 'idle'
local swing = 0
local hits = { taken = 0, zero = 0 }
local function log(...)
print('ASHLAR_COMBAT', ...)
end
-- Stats can only be changed by the actor's own local script.
local function toughen(actor)
local stats = types.Actor.stats
for _, name in ipairs({ 'health', 'fatigue' }) do
local stat = stats.dynamic[name](actor)
stat.base = 5000
stat.current = 5000
end
stats.attributes.agility(actor).base = 100
stats.attributes.strength(actor).base = 60
types.NPC.stats.skills.block(actor).base = 100
types.NPC.stats.skills.shortblade(actor).base = 100
end
I.Combat.addOnHitHandler(function(attack)
local health = attack.damage and attack.damage.health or 0
hits.taken = hits.taken + 1
if attack.successful and health <= 0 then
hits.zero = hits.zero + 1
end
print(string.format('ASHLAR_COMBAT player hit successful=%s health=%.2f blockHeld=%s',
tostring(attack.successful), health, tostring(self.controls.block)))
end)
local function faceEnemy()
local delta = kit.enemy.position - self.position
local target = math.atan2(delta.x, delta.y)
local diff = util.normalizeAngle(target - self.rotation:getYaw())
self.controls.yawChange = util.clamp(diff, -0.1, 0.1)
end
return {
eventHandlers = {
AshlarCombatStart = function(data)
kit = data
toughen(self)
local eq = Actor.getEquipment(self)
eq[Actor.EQUIPMENT_SLOT.CarriedLeft] = data.shield
eq[Actor.EQUIPMENT_SLOT.CarriedRight] = data.blade
Actor.setEquipment(self, eq)
I.Controls.overrideMovementControls(true)
I.Controls.overrideCombatControls(true)
phase, t = 'draw', 0
end,
},
engineHandlers = {
onFrame = function(dt)
if not kit or phase == 'done' then
return
end
t = t + dt
faceEnemy()
self.controls.movement = 0
self.controls.sideMovement = 0
if phase == 'draw' then
Actor.setStance(self, Actor.STANCE.Weapon)
if t > 2 then
phase = 'block'
log('player phase block')
end
elseif phase == 'block' then
self.controls.block = true
self.controls.use = 0
if t > BLOCK_UNTIL then
phase = 'attack'
log('player phase attack')
end
elseif phase == 'attack' then
self.controls.block = false
swing = swing + dt
-- Hold Use to wind up, release to strike, then rest briefly.
self.controls.use = (swing % 1.4 < 0.6) and 1 or 0
if t > ATTACK_UNTIL then
self.controls.use = 0
phase = 'done'
log(string.format('player done hitsTaken=%d zeroDamage=%d enemyDistance=%.0f', hits.taken,
hits.zero, (kit.enemy.position - self.position):length()))
end
end
end,
},
}
+56
View File
@@ -0,0 +1,56 @@
# Headless test scenarios
The OpenMW Game Template has no shields and no hostile actors, so combat changes can't be seen in the plain
headless boot. Scenarios are small test content files of our own (CC0, Lua only, reusing Game Template meshes)
that `docker/ashlar-run.sh` loads on top of the Game Template when asked. The default boot is unchanged.
No commercial game data is used or needed.
## Running one
```bash
docker/ashlar-build.sh
SCENARIO=combat docker/ashlar-run.sh
```
The scenario directory `docker/scenarios/<name>/` is mounted read-only at `/scenario`, added as a `data=` path,
and its `ashlar<name>.omwscripts` file is added as content. `BOOT_SECONDS` defaults to 120 with a scenario (90
without). The run still writes `~/.cache/ashlar/run/boot.png` and `stdout.log`, and then prints the scenario's
log lines and a summary.
## `combat`
`docker/scenarios/combat/` sets up a duel:
- The global script creates a shield and a short blade (both use `meshes/marker_error.dae`) for the player, and
spawns a "Test Duelist" NPC 160 units in front of the player. The duelist's record is a copy of the template's
player record, so it uses the template's body and animations. Both actors get 5000 health and fatigue, Block
and Short Blade 100, and Agility 100, so neither dies or runs out of stamina during the test.
- The duelist equips its shield and blade and starts a normal `Combat` AI package against the player. With
`[Game] ai active blocking` on, its AI raises the block stance when the player winds up an attack in front of
it.
- The player script overrides movement and combat controls, keeps the player facing the duelist, draws the
weapon, holds `self.controls.block` from 2 s to 14 s (the duelist's swings should hit the raised shield), and
then attacks every 1.4 s (holding Use 0.6 s) until 40 s.
- Both sides log every hit they take through `I.Combat.addOnHitHandler` as `ASHLAR_COMBAT ... hit` lines.
The engine logs each successful block at verbose level:
```
Ashlar block: "Player" blocked <attacker> with shield, stance, damage through 0
Ashlar block: <npc id> blocked "Player" with weapon, stance, damage through 1.2
```
`with shield` is a full shield block, `with weapon` a parry. `stance` means the blocker was in the held block
stance (active blocking); `roll` means the classic random block. The run script counts player and NPC blocks
from these lines. A useful run shows at least one of each.
What this checks: that blocks, parries and stamina rules fire end to end with real AI, animation timing and
physical hit detection. What it doesn't check: how combat feels. That still needs a hands-on playtest.
## Adding a scenario
Create `docker/scenarios/<name>/ashlar<name>.omwscripts` and its scripts under
`docker/scenarios/<name>/scripts/ashlar<name>/`. Create records at runtime with `world.createRecord` instead of
shipping an `.omwaddon`, use only Game Template meshes or CC0 assets, and print lines with a distinctive prefix
so the run log can be filtered.