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
movementHeadinginControls::HandleControls; no separate strafe-mode logic needed. - Auto-unlock if the target is destroyed or
Entity.SetActive(target, false). Re-engage by callingCamera.LockOnagain 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()fromonUpdatewhenPlayer.GetPositionis too far fromCamera.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 ± sizein 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.StartIFramescount 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 aPS1TriggerBoxcallingStats.DealDamageon 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;
UVScrollSpeedworks 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). FireMusic.Playon the fog-gate trigger; ducking + crossfade viaMusic.SetVolumeduring 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.Fogcolor tinted toward the boss's theme (red for fire bosses, sickly green for poison ones). Pair with a darkerPS1Skytint viaTintColor. - Sub-scene arena — use
PS1Scene.SubScenesto 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:
- Arena — a sub-scene with low fog, dark sky tint, custom music.
- Fog gate —
PS1TriggerBoxat the doorway, OneShot until defeated (Persist-tracked). - Boss intro cutscene —
PS1Cutscenezooming the camera to the boss + showing aPS1UICanvaswith the boss's name + a roar audio clip. - Boss FSM — 3 states: idle, attack, low_hp. Transitions on HP thresholds.
- Player attacks — copy the showcase's L2 (ranged) + R2 (melee).
- Boss HP bar — bottom-of-screen
PS1UICanvas, scalesfillelement width with boss HP. - Death sequence —
Cutscene.Play("you_died")on player HP 0;Scene.Loadback to the last checkpoint. Boss-death sequence sets Persistgodrick_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.LockOnwould 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.
Related¶
combat_showcase.lua— the reference 229-line implementation.- Lua API → Entity · Physics · Camera · Scene — the called surface.
- FSM graphs · Behavior tree graphs — boss brains.
- PS1Cutscene — intro / phase-transition / death cinematics.