EFPSE FSM (Finite State Machine) — Reference

Last updated: Oct 13, 2025

0) Quick Start

Concept	Syntax
State	`state <NAME> <NEXT\|NONE> <interpolateModels 0\|1>`
Frame	`frame <spriteIndex> <time> <offX> <offY> <offZ> <ACTION...>`

Branch	Notes
`JUMPIF*`	All comparison variants (`EQUALS`,`NEQUALS`,`GEQUALS`,`LEQUALS`,`GREATER`,`LESS`,`HPLESS`).
`JUMPIFNOAMMO`	Jumps when magazine is empty.
`JUMPIFNOAMMOTOTAL`	Jumps when total ammo (mag+spare) is zero.

Vars	Notes
`SETVAR`	Math funcs: `RANDOM,SIN,COS,TAN,ASIN,ACOS,ATAN,ATAN2,POWER,SQRT,ABS,FLOOR,CEIL,CLAMP,MIN,MAX,ROUND`; tokens: `HP,MAXHP,LASTDAMAGE,AMMO,MAGAMMO` (on weapons, HP/MAXHP = player).
`INCREMENT` / `DECREMENT`	Add/Subtract (default 1).

Audio	Signature / Notes
`SOUND`	`SOUND <id> [loop] [minRadius] [falloff] [directionality]` — set `falloff=0` & `directionality=0` for classic 2D.
`STOPSOUND`	`STOPSOUND <id>` — stops a sound started via FSM.
`SOUNDANDATTACK`	One-shot play + attack in same frame.
Move/Pos	Notes
—	—
`MOVE`	Local-space move.
`CHECKPOS`	Writes position to 3 vars.
`PLAYERDISTANCE` / `PLAYERVISIBLE`	Distance/LOS into a var (0/1).

Model	Notes
`ROTMODE 0/1/2/3`	3 = set full rotation.
`SETYAW` / `ADDYAW`	Override/add yaw; variables allowed.
`MODELTEXTURE ... 1 1`	Updates normals/emissive.

HUD & FX	Notes
`HUDIMG`	Re-issue same name to update; name-only to remove; persists in saves.
`PARTICLES` / `CUSTOMPARTICLE`	Custom IDs 0…N contiguous.

1) General Notes

Whitespace & casing: keywords are case-sensitive; spaces matter.
Frame timing: frames do not get skipped; time=0 is valid.
Time applies to the previous image: a line’s time determines how long the previous image stays visible.
Local variables reset on map change/new game.
Save/Load: HUD images and playing sounds persist across saves.

Asset declarations

<BaseName> [startIndex endIndex]
sound <BaseName>

State & frame lines

<STATE_NAME> <NEXT_STATE|NONE> <interpolateModels 0|1>
frame <spriteIndex> <time> <offX> <offY> <offZ> <ACTION...>

2) Decorations FSM

Built-in states: IDLE, DEATH, DEAD

Valid actions (Decorations)

Category	Calls	Notes
Flow/Branch	`NONE`, `READY`, `JUMPIF*`	Standard control flow.
Vars/Math	`SETVAR`, `INCREMENT`,`DECREMENT`,`MULTIPLY`,`DIVIDE`,`MODULO`,`CLAMP`	Supports arrays & math funcs.
Audio	`SOUND`, `STOPSOUND`, `SOUNDANDATTACK`	Spatialized by default.
Movement	`MOVE`, `CHECKPOS`, `PLAYERDISTANCE`, `PLAYERVISIBLE`	Useful for reactive props.
FX/HUD	`PARTICLES`, `CUSTOMPARTICLE`, `HUDIMG`	Particles use local coords.
Model	`MODELTEXTURE`, `ROTMODE`, `SETYAW`, `ADDYAW`	For 3D decorations.
Spawns/Explosions	`SPAWN`, `EXPLOSION`	Typical for breakables.
Attack	`ATTACK`	No weapon-style attack; use `EXPLOSION` or script-driven effects.

Example (Decoration)

state IDLE NONE 0
frame 0 0.25 0 0 0 NONE

state DEATH DEAD 0
frame 1 0.166 0 0 0 NONE
frame 2 0.166 0 0 0 NONE
frame 3 0.166 0 0 0 NONE

state DEAD NONE 0
frame 3 0.25 0 0 0 NONE
frame 3 0.25 0 0 0 NONE

3) Weapons FSM

Built-in states: DRAW, IDLE, ATTACK, ALTATTACK, RELOAD, HOLSTER

Valid actions (Weapons)

Category	Calls	Notes
Flow/Branch	`NONE`, `READY`, `JUMPIF*`, `JUMPIFNOAMMO`, `JUMPIFNOAMMOTOTAL`	Control fire/reload flow.
Vars/Math	`SETVAR`, `INCREMENT`,`DECREMENT`,`MULTIPLY`,`DIVIDE`,`MODULO`,`CLAMP`	`HP/MAXHP` refer to the player here.
Audio	`SOUND`, `STOPSOUND`, `SOUNDANDATTACK`	Looping + stop supported.
Movement	`MOVE`	For view-weapon nudges; test offsets.
FX/HUD	`PARTICLES`, `CUSTOMPARTICLE`, `HUDIMG`	Muzzle sparks, HUD hints.
Model	`MODELTEXTURE`, `ROTMODE`, `SETYAW`, `ADDYAW`	For 3D weapons.
Projectiles	`PROJECTILE ...`	Uses weapon’s projectile config.
Attack	`ATTACK`, `MUZZLEFLASH`	`ATTACK` consumes ammo; `MUZZLEFLASH` is weapon-only.

Notes

Default IDLE is a single frame; READY still works on the first frame.
Frame times are scaled by attack/reload speed at runtime.

Examples (Weapon)

state IDLE NONE 0
frame 1 0.25 0 0 0 READY

state ATTACK IDLE 0
frame 2 1 0 0 0 NONE
frame 3 1 0 0 0 SOUNDANDATTACK 0
frame 4 1 0 0 0 MUZZLEFLASH
frame 5 1 0 0 0 READY
frame 6 1 0 0 0 NONE
frame 7 1 0 0 0 NONE
frame 1 0.25 0 0 0 NONE
frame 1 0.25 0 0 0 NONE

state RELOAD IDLE 0
frame 1 0 0 0 0 NONE
frame 1 0.2 0 0 0 NONE
frame 1 0.2 0 200 0 NONE
frame 1 0.2 0 200 0 RELOAD
frame 1 0.2 0 0 0 SOUND 1

Patterns

state ATTACK IDLE 0
frame 5 0.25 0 0 0 NONE
frame 6 0.0625 0 0 0 READY
frame 6 0.0625 0 0 0 ATTACK
frame 5 0.25 0 0 0 READY
frame 6 0.0625 0 0 0 ATTACK

frame 2 0.00 0 0 0 SOUND 0 1 128 0.25 0.2
frame 3 0.05 0 0 0 SOUNDANDATTACK 1
frame 4 0.00 0 0 0 STOPSOUND 0

4) Enemies FSM

Built-in states: IDLE, SEE, CHASE, ATTACK, FLEE, HURT, DEATH, XDEATH, DEAD
(Enemy movement occurs in CHASE.)

Valid actions (Enemies)

Category	Calls	Notes
Flow/Branch	`NONE`, `READY`, `JUMPIF*`	Gate between SEE/CHASE/ATTACK/etc.
Vars/Math	`SETVAR`, `INCREMENT`,`DECREMENT`,`MULTIPLY`,`DIVIDE`,`MODULO`,`CLAMP`	Supports arrays & math funcs.
Audio	`SOUND`, `STOPSOUND`, `SOUNDANDATTACK`	Spatialized by default.
Movement	`MOVE`, `CHECKPOS`, `PLAYERDISTANCE`, `PLAYERVISIBLE`	AI steering helpers.
FX/HUD	`PARTICLES`, `CUSTOMPARTICLE`, `HUDIMG`	Blood, alerts, HUD hints.
Model	`MODELTEXTURE`, `ROTMODE`, `SETYAW`, `ADDYAW`	For 3D enemies.
Projectiles	`PROJECTILE ...`	Can target `height=player`.
Attack	`ATTACK`	Executes configured enemy attack.

Example (Enemy)

state IDLE NONE 0
frame 0 0.125 0 0 0 NONE
frame 0 0.125 0 0 0 READY

state SEE CHASE 0
frame 0 0.125 0 0 0 NONE
frame 0 0.125 0 0 0 READY

state CHASE NONE 0
frame 1 0.25 0 0 0 NONE
frame 2 0.25 0 0 0 NONE
frame 3 0.25 0 0 0 NONE
frame 4 0.25 0 0 0 READY

state FLEE NONE 0
frame 1 0.25 0 0 0 NONE
frame 2 0.25 0 0 0 NONE
frame 3 0.25 0 0 0 NONE
frame 4 0.25 0 0 0 READY

state ATTACK CHASE 0
frame 5 0.25 0 0 0 NONE
frame 5 0.25 0 0 0 NONE
frame 6 0.0625 0 0 0 MUZZLEFLASH
frame 6 0.0625 0 0 0 ATTACK
frame 0 0.25 0 0 0 NONE
frame 0 0.25 0 0 0 READY

state HURT CHASE 0
frame 7 0.25 0 0 0 NONE
frame 8 0.25 0 0 0 NONE

state DEATH DEAD 0
frame 9 0.166 0 0 0 NONE
frame 10 0.166 0 0 0 NONE
frame 11 0.166 0 0 0 NONE

state XDEATH DEAD 0
frame 9 0.166 0 0 0 NONE
frame 10 0.166 0 0 0 NONE
frame 11 0.166 0 0 0 NONE

state DEAD NONE 0
frame 12 0.125 0 0 0 NONE
frame 12 0.125 0 0 0 NONE

5) Cross‑Entity Action Matrix

Action	Decorations	Weapons	Enemies	Notes
`NONE`, `READY`	✓	✓	✓	Flow control.
`JUMPIF*`	✓	✓	✓	Branching (HP/vars).
`SETVAR`,`INC/DEC`,`MUL/DIV/MOD`,`CLAMP`	✓	✓	✓	Arrays & math funcs supported.
`SOUND`,`STOPSOUND`,`SOUNDANDATTACK`	✓	✓	✓	Use loop/stop for ambience.
`MOVE`,`CHECKPOS`	✓	✓	✓	Local movement / query.
`PLAYERDISTANCE`,`PLAYERVISIBLE`	✓	—	✓	Visibility check not meaningful on weapons.
`PARTICLES`,`CUSTOMPARTICLE`,`HUDIMG`	✓	✓	✓	HUD persists in saves.
`MODELTEXTURE`,`ROTMODE`,`SETYAW`,`ADDYAW`	✓	✓	✓	3D model control.
`SPAWN`,`EXPLOSION`	✓	—	✓	Decorations/enemies only.
`ATTACK`	—	✓	✓	Weapon consumes ammo; enemy triggers configured attack.
`MUZZLEFLASH`	—	✓	—	Weapon-only visual.
`PROJECTILE ...`	—	✓	✓	Height can target `player`.

6) Tips

For the last visible image of a state, add a trailing frame line to donate its on‑screen time.