Skip to content

Combat patterns

A boss-encounter / souls-like / action-game recipe page. The PS1Godot runtime ships with the primitives for combat — projectile spawn + raycast hit detection, melee overlap boxes, screen shake, hitstop, tag-based lock-on, FSM/BT enemy brains — but no single page tied them together until now. This is that page.

The reference implementation is godot-ps1/demo/scripts/combat_showcase.lua — 229 lines exercising every combat-relevant API the runtime ships. Read it; this page references its patterns.

What you've got

Surface API Use for
Spawn / despawn Entity.Spawn · Entity.Destroy Pooled projectiles, enemies, pickups
Tags Entity.SetTag · FindByTag · FindNearest "Is this thing an enemy / pickup / projectile?"
Hit detection Physics.Raycast · Physics.OverlapBox Bullet vs target / melee swing
Game-feel Camera.ShakeRaw · Scene.PauseFor Hit feedback, hitstop
Camera Camera.GetForward · Camera.SetMode · Camera.SetH 1st/3rd-person, manual yaw
Input freeze Controls.SetEnabled Cutscenes, dialog pauses
AI brains PS1Graph FSM + Behavior Tree Boss state machines
Atmosphere PS1Sky · PS1Scene fog · Music.SetVolume Arena vibe, ducking ambient
Persistence Persist.Get · Persist.Set "Have I killed this boss?"

Projectile combat

The showcase's L2 path. Spawn a tagged bullet, give it a direction + TTL, raycast every frame to detect hits.

local TAG_BULLET = 1
local TAG_ENEMY  = 2

local bullets = {}  -- { handle, dir, ttl } per entry
local BULLET_SPEED  = 1
local BULLET_RAYCAST_DIST = 2

local function spawnBullet()
    local dir = Camera.GetForward()
    -- Spawn point: a bit ahead of camera in the look direction
    local cam = Camera.GetPosition()
    local spawnPos = Vec3.new(
        cam.x + dir.x * 4,
        cam.y + 1,  -- chest height (Y is inverted)
        cam.z + dir.z * 4)
    local b = Entity.Spawn(TAG_BULLET, spawnPos)
    if b then
        bullets[#bullets + 1] = { handle = b, dir = dir, ttl = 60 }
        Camera.ShakeRaw(246, 6)  -- ~0.06 world units of shake
    end
end

function onUpdate(self, dt)
    if Input.IsPressed(Input.L2) then spawnBullet() end
    for i = #bullets, 1, -1 do
        local b = bullets[i]
        local hit = Physics.Raycast(
            Entity.GetPosition(b.handle), b.dir, BULLET_RAYCAST_DIST)
        if hit and Entity.GetTag(hit.object) == TAG_ENEMY then
            Entity.Destroy(hit.object)       -- the enemy
            Entity.Destroy(b.handle)         -- the bullet
            Camera.ShakeRaw(614, 14)         -- ~0.15 — solid hit
            Scene.PauseFor(4)                -- 4-frame hitstop
            table.remove(bullets, i)
        else
            -- advance + decay
            -- ...
        end
    end
end

The hitstop (Scene.PauseFor(4)) is the single biggest game-feel unlock — every gameplay system freezes for 4 frames, then resumes. Cheaper than animation work, conveys impact instantly.

Melee combat

The showcase's R2 path. Overlap a box in front of the player; every overlapping tagged entity takes a hit.

local MELEE_COOLDOWN = 20  -- frames between swings
local meleeCooldown = 0

local function meleeSwing()
    if meleeCooldown > 0 then return end
    meleeCooldown = MELEE_COOLDOWN

    local cam = Camera.GetPosition()
    local fwd = Camera.GetForward()
    -- AABB in front of the player, 2 units forward, 1.5×1.5×2 size
    local minV = Vec3.new(cam.x + fwd.x * 1 - 1, cam.y, cam.z + fwd.z * 1 - 1)
    local maxV = Vec3.new(cam.x + fwd.x * 3 + 1, cam.y + 2, cam.z + fwd.z * 3 + 1)
    local hits = Physics.OverlapBox(minV, maxV, TAG_ENEMY)
    if #hits > 0 then
        for i = 1, #hits do Entity.Destroy(hits[i]) end
        Camera.ShakeRaw(491 + 164 * #hits, 8 + #hits)
        Scene.PauseFor(5 + #hits)
    else
        Camera.ShakeRaw(123, 5)  -- whiff feedback
    end
end

Two notes:

  • Scale shake + hitstop by hit count. Hitting 3 enemies in one swing should feel weightier than hitting 1.
  • Whiff feedback matters. Even a missed swing benefits from a tiny camera shake — confirms input was received.

Twin-stick camera

Already the default for analog pads

Controls::HandleControls (psxsplash-main/src/controls.cpp, lines 217–227) wires the right stick to player yaw and pitch automatically. Plug in an analog pad and you have twin-stick out of the box — zero Lua required.

The runtime tick already does, every frame:

// Pseudocode, paraphrased from controls.cpp:217-227.
if (abs(rightStickX) > deadzone) playerRotationY += rightStickX * rotSpeed * dt;
if (abs(rightStickY) > deadzone) playerRotationX -= rightStickY * rotSpeed * dt;
// Pitch clamped to [-0.5π, +0.5π] so the player can't flip upside down.

The player yaw drives the camera follow in scenemanager.cpp:947, so right-stick input visibly turns the player and the camera moves with them. This is the modern-action default (Tomb Raider, GTA, Bayonetta lock-off) — you face where you look.

Input.GetAnalog(Input.RIGHT_STICK) is exposed for Lua-side reads if a scene needs custom behavior (e.g., a HUD reticle that lags slightly behind the camera). You don't need to call it to get the baseline feel.

L1 / R1 fallback for digital pads

Digital pads have no sticks. The same HandleControls path falls back to L1 / R1 for rotation when the pad reports digital (controls.cpp:163-165). Authors don't have to fork on pad type — the runtime picks the right input automatically.

Tuning gaps

Sensitivity, deadzone, and pitch clamp are global runtime constants — not per-scene tunable today. A heavy-character boss arena that wants a slower turn rate and a fast-action scene that wants snappy control both use the same hardcoded values.

The boss-encounter primitives RFC primitive 5 proposes per-scene tunable fields on PS1Player (YawSensitivity, PitchSensitivity, StickDeadzone) plus an opt-out flag for fixed-camera scenes that want pure-button control.

Decoupling camera from player (lock-on / strafe)

The current default couples camera yaw to player yaw — they rotate together. For lock-on mode (Elden Ring's signature control), the camera needs to track a target while the player strafes around it, so player yaw and camera yaw decouple.

That decoupling is what the lock-on primitive (RFC § primitive 4) delivers — it's the missing piece for souls-like feel, not twin-stick itself.

Lock-on (Camera.LockOn)

The runtime ships engine-side soft-lock. Call Camera.LockOn(target) on an entity handle; each frame the runtime computes the yaw from player→target and overrides playerRotationY with it. The third-person rig follows automatically, so the camera tracks the target. Side-effects:

  • Camera tracks, the player can't manually rotate away while locked — right-stick yaw and L1/R1 rotation are visually suppressed (their changes get overwritten by the per-frame snap).
  • Stick input becomes target-relative. Forward = toward target, left-stick X = strafe orthogonal. This falls out of the lock-on yaw being used as movementHeading in Controls::HandleControls; no separate strafe-mode logic needed.
  • Auto-unlock if the target is destroyed or Entity.SetActive(target, false). Re-engage by calling Camera.LockOn again with a valid target.

Toggle pattern:

local TAG_ENEMY = 2

function onUpdate(self, dt)
    -- R3 toggles lock-on (showcase convention: R3 is free on both
    -- digital and analog pads)
    if Input.IsPressed(Input.R3) then
        if Camera.IsLocked() then
            Camera.LockOff()
            Camera.ShakeRaw(82, 4)  -- subtle confirm
        else
            local p = Camera.GetPosition()
            local target = Entity.FindNearest(p, TAG_ENEMY)
            if target then
                Camera.LockOn(target)
                Camera.ShakeRaw(82, 4)
            end
        end
    end
end

Reticle (still a Lua pattern)

A visual reticle floating over the locked target isn't built-in. The simplest approach today: tag the locked entity with a sentinel value (e.g. 9) on lock and revert on unlock, then have your scene's render-side authoring (a small overlay sprite parented to the locked entity) key off that tag. Or animate a UI canvas to follow the entity's screen-space position in onUpdate using Entity.GetPosition + a 3D-to-2D projection helper.

Engine-side reticle support (a sprite that follows the locked entity in screen space automatically) is on the queue but not critical — the gameplay loop works fine without it for v1.

What still needs Lua

The runtime handles the camera + movement coupling. What it doesn't do:

  • Lock-on targeting heuristic — the runtime takes whatever entity you pass. Picking the right one (nearest? in front of player? most-threatening?) is a per-game policy your Lua decides.
  • Lock-switch (cycle to next enemy while locked) — read right-stick X and call Camera.LockOn(nextTarget) when it passes a threshold.
  • Lock-break on distance — call Camera.LockOff() from onUpdate when Player.GetPosition is too far from Camera.GetLockTarget. Souls usually breaks lock at ~25 m.

Boss HP

Attach a PS1Stats resource to the boss's PS1MeshInstance.Stats slot. The runtime tracks current HP + MaxHP per-entity; read via Lua's Stats.GetHP.

-- In the boss script. `self` is the boss entity handle.
local DAMAGE_PER_HIT = 10

local function takeDamage(amount)
    local hp = Stats.GetHP(self) - amount
    Stats.SetHP(self, hp)            -- runtime clamps to [0, MaxHP]
    Camera.ShakeRaw(491, 8)
    if Stats.GetHP(self) <= 0 then onDeath() end
    updateHPBar()
end

local function updateHPBar()
    local canvas = UI.FindCanvas("boss_hp")
    if canvas >= 0 then
        local bar = UI.FindElement(canvas, "fill")
        local hp     = Stats.GetHP(self)
        local maxHP  = Stats.GetMaxHP(self)
        -- Width proportional to remaining HP. Original bar W = 200.
        local fillW  = (hp * 200) // maxHP
        UI.SetElementW(bar, fillW)
    end
end

Stamina + Mana have the parallel pattern — Stats.GetStamina / Stats.SetStamina / Stats.GetMaxStamina and the same for Mana. Author the HUD bars the same way and read the matching stat.

For games without stamina or mana, leave MaxStamina / MaxMana at 0 on the PS1Stats resource — every query returns 0, your HUD authoring can branch on max to skip those bars.

The HP bar canvas is a normal PS1UICanvas:

Scene (PS1Scene)
└── BossHPCanvas (PS1UICanvas, Name = "boss_hp", VisibleOnLoad = false)
    ├── BG    (PS1UIElement, Type = Box, color = dark)
    ├── Fill  (PS1UIElement, Type = Box, color = blood red, X/Y/W/H authored)
    └── Label (PS1UIElement, Type = Text, "Margit, the Fell Omen")

Show on encounter start: UI.SetCanvasVisible(canvas, true). Hide on boss death.

Hurtboxes (weak-point crits)

Author PS1HurtBox children under a PS1MeshInstance to give the entity weak-point zones with per-zone damage multipliers. Classic use case: boss head = 2× crit, body = 1×, armored legs = 0.5×.

Margit (PS1MeshInstance, Stats = margit_stats.tres)
├── PS1HurtBox (head, Size = (0.4, 0.3, 0.4), Multiplier = 200)
├── PS1HurtBox (body, Size = (0.8, 1.2, 0.5), Multiplier = 100)
└── PS1HurtBox (legs, Size = (0.6, 0.8, 0.5), Multiplier =  50)

At hit-detection time, swap Physics.OverlapBox for Physics.OverlapBoxDetailed:

local BASE_DAMAGE = 10

local function meleeSwing()
    local minV, maxV = ... -- as before
    local hits = Physics.OverlapBoxDetailed(minV, maxV)
    for i = 1, #hits do
        local hit = hits[i]
        -- multiplier is a percent: 100 = 1×, 200 = 2×.
        local damage = (BASE_DAMAGE * hit.multiplier) // 100
        Stats.DealDamage(hit.object, damage, self)
    end
end

When multiple hurtboxes on the same entity overlap the query box, the runtime returns the highest multiplier for that entity — authoring head + body + legs with descending multipliers gives a clean "best zone wins" feel without per-call Lua dedup.

Entities without any PS1HurtBox children don't appear in OverlapBoxDetailed results at all. Use Physics.OverlapBox for the "is anything here?" query — OverlapBoxDetailed is specifically the hurtbox-zone query.

Hurtbox limitations

  • Axis-aligned only. Hurtboxes ignore the entity's rotation; the AABB is entity.pos + offset ± size in world space. For a rotating boss the head zone effectively wobbles around its true position. Good enough for v1; rotated-box queries are future work.
  • No state. Can't toggle a hurtbox "on" only during certain animations. For a "guard break leaves you vulnerable" pattern, author one hurtbox for the body normally and toggle the entity's Controls.StartIFrames count instead to gate the whole entity.

Damage dispatch (Stats.DealDamage)

Once you have PS1Stats authored, the canonical damage entry point is Stats.DealDamage:

-- Where you used to call Entity.Destroy(victim) directly:
local applied = Stats.DealDamage(victim, 10, self)
if applied > 0 then
    Camera.ShakeRaw(614, 14)
    Scene.PauseFor(4)
end
if Stats.GetHP(victim) <= 0 then
    -- HP hit zero — your call what happens. Destroy / play
    -- death anim / drop loot / etc.
    onDeath(victim)
end

DealDamage returns the damage that actually landed. 0 means the entity is invulnerable — either i-frames active (the dodge case below), already at 0 HP, or no stats authored. Branch on the return value before playing impact feedback so whiffing a dodging enemy doesn't flash hit-confirm shake.

The runtime fires onDamage(self, applied, source) on the target after debiting HP. Use it for hit-reaction state changes:

-- In the boss's script:
function onDamage(self, applied, source)
    -- Phase transition at 50%
    if Stats.GetHP(self) < Stats.GetMaxHP(self) // 2
       and not self.phase2_triggered then
        self.phase2_triggered = true
        Cutscene.Play("phase2_intro")
    end

    -- Brief hitstun
    Controls.StartIFrames(self, 8)
end

onDamage is informational — it can't override the amount. Authors who want override behavior call Stats.GetHP / Stats.SetHP manually and skip DealDamage.

Dodge / roll

Souls-like dodge: directional roll with i-frames, stamina cost, cooldown. Most of it is Lua-side recipe; the engine provides the i-frame primitive that the damage system honors.

local DODGE_FRAMES   = 18  -- total dodge animation duration
local IFRAME_WINDOW  = 12  -- subset where i-frames are active —
                           -- shorter than DODGE_FRAMES so late
                           -- dodges get punished
local STAMINA_COST   = 25
local DODGE_COOLDOWN = 30
local DODGE_SPEED    = 0.25  -- world units / frame

local dodgeFrames = 0
local dodgeDir = { x = 0, z = 0 }
local cooldown = 0

function onUpdate(self, dt)
    if cooldown > 0 then cooldown = cooldown - 1 end

    -- Trigger a dodge on Circle if available
    if cooldown == 0
       and dodgeFrames == 0
       and Input.IsPressed(Input.CIRCLE)
       and Stats.GetStamina(self) >= STAMINA_COST then

        -- Direction: left-stick if held, otherwise player-facing back
        local lx, ly = Input.GetAnalog(Input.LEFT_STICK)
        if math.abs(lx) < 0.2 and math.abs(ly) < 0.2 then
            -- No stick input → back-step. Use player yaw to compute.
            local rot = Player.GetRotation()
            -- forward = (sin(yaw), cos(yaw)) so back = negated
            dodgeDir.x = -math.sin(rot.y * math.pi)
            dodgeDir.z = -math.cos(rot.y * math.pi)
        else
            -- Stick direction (camera-relative; for lock-on this would
            -- compute strafe-relative — see Camera.LockOn primitive 4)
            dodgeDir.x = lx
            dodgeDir.z = -ly
        end

        dodgeFrames = DODGE_FRAMES
        cooldown = DODGE_COOLDOWN
        Stats.SetStamina(self, Stats.GetStamina(self) - STAMINA_COST)
        Controls.StartIFrames(self, IFRAME_WINDOW)
        -- SkinnedAnim.Play(self, "dodge")  -- when skinned animation lands
    end

    -- Active dodge — manual movement override
    if dodgeFrames > 0 then
        local p = Entity.GetPosition(self)
        Entity.SetPosition(self, Vec3.new(
            p.x + dodgeDir.x * DODGE_SPEED,
            p.y,
            p.z + dodgeDir.z * DODGE_SPEED))
        dodgeFrames = dodgeFrames - 1
    end
end

Why i-frames need engine support: the collision system's contact resolution and Stats.DealDamage's damage debit both honor Controls.StartIFrames automatically. A Lua-only i-frame implementation could only filter Lua-initiated queries — it couldn't block damage from runtime-driven collision (an enemy swinging into the player). The engine-side counter is the single source of truth.

Boss phases

FSM graphs handle this cleanly. Each phase is a state; the condition for entering the next phase is "current HP below a threshold."

[idle] →on_aggro→ [phase1_attack] →on_low_hp(50)→ [phase1_exit_cutscene]
                                                        ↓
                                                    [phase2_intro]
                                                        ↓
                                                  [phase2_attack] →on_low_hp(0)→ [death]

Conditions on transitions test against Persist-backed values:

-- in the boss's onUpdate
Persist.Set("boss_hp", hp)
-- FSM's transition guard checks Persist.Get("boss_hp") < 50

The phase exit cutscene (boss screams + transformation + name reveal) is a PS1Cutscene — multi-track camera + audio + object animation, fired by the FSM transition into phase1_exit_cutscene.

Fog gates and scrolling-UV effects

The visible "fog wall" in Elden Ring is a translucent textured plane with the texture scrolling diagonally. PS1Godot ships PS1MeshInstance.UVScrollSpeed (Vector2) for exactly this — the runtime adds an accumulated offset to every vertex UV before each frame's primitive submission. uint8 wrap is intentional; a power-of-2 texture scrolls cleanly across its full range.

Authoring a fog gate

FogWall (PS1MeshInstance)
  Mesh: PlaneMesh (sized to the doorway)
  Material: PS1Material with a fog/noise texture (4 or 8 bpp,
            translucent material with AlphaMode = Translucent)
  UVScrollSpeed: (12, 6)   — diagonal flow, gentle

FogGateTrigger (PS1TriggerBox)
  Size: matches the doorway opening
  ScriptFile: fog_gate.lua
-- fog_gate.lua
function onTriggerEnter(self, index)
    if Persist.Get("godrick_gate_crossed") then return end
    Persist.Set("godrick_gate_crossed", 1)
    Audio.PlaySfx("fog_gate_whoosh")
    Cutscene.Play("godrick_intro")
    -- Cutscene's OnFinishLua fires Camera.LockOn(godrick) and
    -- Controls.SetEnabled(true) when the intro finishes.
end

That's it — no PS1FogGate mega-component, no special engine support beyond the UV-scroll feature. The gate composes from primitives you already know.

Other UV-scroll use cases

  • Waterfalls — vertical strip, UVScrollSpeed = (0, 32). Try a slight Y-tile texture for water-fall caustics.
  • Lava / poison surfaces — (2, 4) for slow ooze. Pair with a PS1TriggerBox calling Stats.DealDamage on overlap if it hurts.
  • Conveyor belts — (0, 24) along the belt direction. Move the player on overlap via a sibling trigger.
  • Spell circles — (8, 8) for diagonal spin. Better than no motion on a magic-circle prop.
  • Scrolling text overlays — UI canvases use sprite primitives too; UVScrollSpeed works on the underlying mesh.

The runtime cost is one branch + six uint8 adds per textured triangle on objects with non-zero scroll. Cheap.

Death / respawn

No formal "respawn point" system. Wire it yourself:

function onPlayerDeath()
    Cutscene.Play("you_died")  -- 2s fade-to-black with title
    -- Cutscene.OnFinishLua respawns:
    Scene.Load(Persist.Get("respawn_scene") or 0)
    Player.SetPosition(
        Persist.Get("respawn_x") or 0,
        Persist.Get("respawn_y") or 0,
        Persist.Get("respawn_z") or 0)
end

Respawn-point checkpoints set the Persist keys on activation (PS1TriggerBox with a "save_point" script that writes the player's current position).

Atmosphere

The arena fight's vibe is half the encounter:

  • Music — author a 2-stage PS1MusicSequence (low intensity before aggro, high intensity during fight). Fire Music.Play on the fog-gate trigger; ducking + crossfade via Music.SetVolume during phase transitions.
  • Audio cues — boss roar on appearance, footstep on every attack (give the player audible patterns to read). All via PS1AudioClip + Audio.PlaySfx.
  • Fog and color — a darker PS1Scene.Fog color tinted toward the boss's theme (red for fire bosses, sickly green for poison ones). Pair with a darker PS1Sky tint via TintColor.
  • Sub-scene arena — use PS1Scene.SubScenes to load a dedicated "boss arena" scene when the player enters the fog gate. Keeps the asset budget tight + lets the arena have its own VRAM packing.

Putting it together — minimum viable Elden Ring–style boss

A first encounter you can ship today, with zero engine changes:

  1. Arena — a sub-scene with low fog, dark sky tint, custom music.
  2. Fog gate — PS1TriggerBox at the doorway, OneShot until defeated (Persist-tracked).
  3. Boss intro cutscene — PS1Cutscene zooming the camera to the boss + showing a PS1UICanvas with the boss's name + a roar audio clip.
  4. Boss FSM — 3 states: idle, attack, low_hp. Transitions on HP thresholds.
  5. Player attacks — copy the showcase's L2 (ranged) + R2 (melee).
  6. Boss HP bar — bottom-of-screen PS1UICanvas, scales fill element width with boss HP.
  7. Death sequence — Cutscene.Play("you_died") on player HP 0; Scene.Load back to the last checkpoint. Boss-death sequence sets Persist godrick_dead = 1.

Total scripting: ~150 lines of Lua + the FSM graph + 2 cutscenes.

A note on math performance

PSX has no hardware square root or trig. Performance order, fastest first, for the "how far / what angle / how close" patterns that recur throughout combat code:

Task Use Why
"Is target within range?" Compare squared distances (dx*dx + dz*dz < radius_sq) No sqrt at all. Free.
"How far is the target?" (gameplay feel) Math.LengthApprox(dx, dz) Alpha-max-plus-beta-min — 3.4% max error, two multiplies, no iteration. PSX-era convention.
"How far is the target?" (exact) Math.Sqrt(dx*dx + dz*dz) Bit-by-bit binary search, up to 16 iterations. Don't reach for it in onUpdate unless you need the precision.
"What direction to the target?" Math.Atan2(dx, dz) Octant-fold, no iteration. Returns the pi-fraction Entity.SetRotationY consumes directly.

For dodge cooldowns, AI radius checks, swing hit-detection — all use squared. For "draw a distance number on the HUD" or normalizing a direction vector — use LengthApprox. Save Math.Sqrt for one-shot calculations that genuinely need exactness.

What's not easy today

If your encounter design needs any of these, the patterns above get awkward and a first-class primitive would help. Listed in the boss encounter primitives RFC:

  • Lock-on with camera tracking — today's Lua loop is correct but jittery on low frame counts; engine-side Camera.LockOn would fix that.
  • Hurtboxes vs hitboxes — distinct weak-points (boss head as crit zone) need first-class authoring.
  • Stagger / poise — running a poise counter in Lua works but the dispatch (onStagger(self)) wants to be a runtime callback, not a Lua poll.