top of page

FSM


FSM (Finite State Machine) Manual

Easy FPS Editor / Easy FPS Hub


Overview


FSM (Finite State Machine) allows you to extend sprite animation, logic, and entity behavior far beyond what the editor alone provides.

With FSMs you can:

  • Control animation frame count and speed

  • Override editor-based attack/reload timing

  • Add custom logic (alt attacks, taunts, phases)

  • Create complex deaths, effects, and transitions

  • Implement advanced weapon and enemy behavior

An FSM is a text file that defines:

  • What sprites an entity uses

  • How long frames stay on screen

  • What actions occur per frame

  • How states transition

Once an FSM is used:

All timing and behavior is controlled by the FSM not the editor.

2. Creating an FSM File

File Requirements


  • Extension: .states

  • File name must exactly match the entity name in the editor

  • Location:

ProjectName/States/

Supported Entities


  • Weapons

  • Enemies

  • Decorations

3. Best Practices & Engine Rules (READ THIS)

Formatting Rules


  • No spaces or tabs before any line

  • Keywords are CASE SENSITIVE

  • Whitespace matters, extra spaces break parsing

  • Only latin characters are allowed


Frame Timing


  • 0.0167 = one frame at 60 FPS

  • Very small values can cause frame skipping

  • Newer DEV builds allow frame time 0

    • Useful for calculations, jumps, and variable logic

    • FSM execution is now FPS-independent


⚠ Critical Bug Workaround


The first line of EVERY state must be NONE.

This line is ignored internally and avoids a known FSM bug.

Additionally:

  • The first actual frame must be the first visible animation frame

  • Using frame 0 as a dummy can cause animation jumps


4. Loading Assets


At the top of the FSM file, this is where we load the assets used by the FSM 

image Decoration 0 3

Loads Decoration0 → Decoration3 (indexed from 0).

image Decoration

Loads a single sprite.

Sprite folders

ProjectName/Sprites/Decorations
ProjectName/Sprites/Enemies
ProjectName/Sprites/Weapons

⚠ Weapon sprites must include frame 0 (used for floor pickup).

Sounds

sound WeaponFire

Loads a sound and assigns it an index

(sounds start at 0 and count up. so the second sound loaded would actually be counted as 1)


State Definition

state IDLE NONE 0

Parameters

  1. State name

  2. Next state (NONE = loop or frame-based execution)

  3. Interpolate model frames (3D only: 0 or 1)


Execution Notes


  • nextstate NONE → state executes once per frame

  • Improves logic precision and performance

  • FSM timing no longer skips at high FPS


6. Frames

Frame Syntax


frame sprite time x y z action

Parameters

  • sprite – sprite index

  • time – duration in seconds

  • x y z – offsets (weapons only)

  • action – FSM command

Important:Frame time affects how long the previous frame stays visible.


7. Built-In States

Decorations

State

Description

IDLE

Initial state

DEATH

HP ≤ 0

DEAD

FSM halts

REMOVE

Removes entity

Weapons

State

Description

IDLE

Default

DRAW

Equip animation

HOLSTER

Unequip animation

ATTACK

Left click

ALTATTACK

Right click

RELOAD

Reload

Enemies

State

Description

IDLE

Initial

SEE

Player detected

CHASE

Movement

ATTACK

Attack logic

FLEE

Retreat

HURT

Damage reaction (spawns blood)

DEATH

HP ≤ 0

XDEATH

Manual death

DEAD

FSM terminates

8. Actions

Core

NONE
READY
ATTACK

⚠ READY is mandatory after any attack.

Math

INCREMENT var [value]
DECREMENT var [value]
MULTIPLY var value
DIVIDE var value
MODULO var value
CLAMP var min max

Variables

SETVAR name value

Supports:

  • RANDOM(min,max)

  • HP, MAXHP, LASTDAMAGE

  • AMMO, MAGAMMO

  • Math functions: ABS, MIN, MAX

  • global. and map. prefixes


Jumps


JUMPIFEQUALS var value state
JUMPIFNEQUALS var value state
JUMPIFGREATER var value state
JUMPIFLESS var value state
JUMPIFGEQUALS var value state
JUMPIFLEQUALS var value state
JUMPIFHPLESS value state

Sound


SOUND id
SOUNDANDATTACK id
STOPSOUND id

Health

(these work locally to the entity, so HEAL will heal the entity the command originates from)


HEAL value
HURT value
SETHP value

Position & Movement


CHECKPOS x y z
MOVE x y z

⚠ Older builds returned negative Y — fixed in newer DEV builds.

Particles


PARTICLES img count life x,y,z dx,dy,dz
CUSTOMPARTICLE id life x,y,z dx,dy,dz scale gravity

⚠ Custom particles must start at Custom0 with no gaps.

Spawning & Effects


SPAWN name x,y,z f,v
EXPLOSION name radius [damage]
REMOVE (removes entity on this command)

Default explosion damage: 80

Camera & Models


MODELTEXTURE path [var] [normals] [emissive]
HUDIMG name x y scale path layer
CAMSPEED value
ZOOM value
SETYAW value
ADDYAW value
ROTMODE mode

Enemy-Only


PROJECTILE [angle] [absolute] [height] [spread]
REMOVE

Weapon-Only


JUMPIFLESSAMMO state
JUMPIFNOAMMO state
JUMPIFNOAMMOTOTAL state
GIVEAMMO value [fromTotal]
TAKEAMMO value [fromTotal]
SETAMMO value [fromTotal]
RELOAD
MUZZLEFLASH
SETSTAT stat value

9. Example FSMs

Basic Weapon FSM

image Weapon 0 7
sound WeaponFire
sound WeaponReload

state IDLE NONE 0
frame 1 0.25 0 0 0 NONE
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

state RELOAD IDLE 0
frame 1 0.1 0 0 0 RELOAD
frame 1 0.1 0 0 0 SOUND 1

Basic Enemy FSM

image Enemy 0 12

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

state CHASE NONE 0
frame 1 1 0 0 0 NONE
frame 4 1 0 0 0 READY

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

state DEATH DEAD 0
frame 9 0.166 0 0 0 NONE

Click-to-Fire Weapon

(Prevents holding trigger)

state IDLE NONE 0
frame 1 0.01 0 0 0 SETVAR canShoot 1
frame 1 0.1 0 0 0 READY

state ATTACK IDLE 0
frame 1 0.01 0 0 0 JUMPIFEQUALS canShoot 0 IDLE
frame 1 0.01 0 0 0 SETVAR canShoot 0
frame 4 0.03 0 0 0 SOUNDANDATTACK 0
frame 7 0.03 0 0 0 READY

10. FSM Quick Reference Sheet

Must-Know Rule

  • .states file, exact name matchs

  • No leading whitespace

  • First frame of every state = NONE

  • Always use READY

  • Frame time 0 allowed in DEV builds

  • Weapon sprites must include frame 0


Core Commands

READY
ATTACK
SOUND
SOUNDANDATTACK
SETVAR
JUMPIFGEQUALS
JUMPIFLEQUALS
JUMPIFEQUALS
SPAWN
EXPLOSION
CUSTOMPARTICLE
REMOVE
MOVE

Timing Reference

FPS

Frame Time

60

0.0167

30

0.0333

15

0.0666

Enemy FSM Behavior Flow Diagram


        +------+
        | IDLE | (enemy will briefly enter IDLE if player is too close)
        +--+---+
           |
           | sees player
           v
        +------+
        | SEE  |
        +--+---+
           |
           v
        +--------+
        | CHASE  |<----------------+
        +--+-----+                 |
           |                       |
           | in range              |
           v                       |
        +--------+                 |
        | ATTACK |                 |
        +--+-----+                 |
           | READY                 |
           +-----------------------+

HURT can interrupt:
   ANY STATE --> HURT --> CHASE / FLEE

HP <= 0:
   ANY STATE --> DEATH --> DEAD

Important Notes

  • Enemy only moves in CHASE

  • Blood spawns only in HURT

  • XDEATH is manual (not automatic)

  • DEAD halts FSM


Weapon FSM Flow Diagram


           +-------+
           | DRAW  |  (optional)
           +---+---+
               |
               v
+-------+   +-------+   LMB        +---------+
|HOLSTER|<--| IDLE  | ---------->  | ATTACK  |
+-------+   +---+---+              +----+----+
                    |                    |
                    | R(has ammo)        | READY
                    v                    v
                +--------+           +-------+
                | RELOAD | --------> | IDLE  |
                +--------+           +-------+

ALTATTACK (RMB) branches from IDLE if defined

Notes

  • READY must be called after Attack Command in ATTACK or ALTATTACK

  • ATTACK returns to IDLE (usually)

  • DRAW / HOLSTER override default weapon switching if present

bottom of page