Personal EFPSE Scripting Reference

EDITOR NOTE:

This reference is a WIP (and will probably always be)

At this point in time, I wouldn’t using this reference as gospel.

Keep the Unofficial Wiki close and check Clark’s readme’s for how newer features may work, anything I missed or am incorrect about, etc.

Search through the Discord channels for info, ask for help but make sure you’ve done enough investigation on your own first

Some info below is likely incorrect, as I am in the process of validating everything as I am learning this engine myself

Hope this helps :)

⠀

1) Script Types & Entry Points

1.1 Map Script — `MapName.script`

Auto-runs at the start of the map sharing this script’s name.
Usage: Intros, cutscenes, setup. End with map start (or map return<1-3>).

Example Snippet:

status "hello world"

1.2 Map Loop Script — `MapName_loop.script`

Runs continuously while the map is active.
Loops through the script, from top to bottom, every tick.
Frame-Dependency means that the script may only tick as much as the frames-per-second of the game.
Optional cap can be set in editor to limit loop ticks per second (0 = unlimited; still capped by FPS). This may be useful for ensuring stability.
Timing by seconds may be used by comparing $global.deltaTime to the tick rate for frame-rate independent logic.

Example Snippet:

time+=$global.deltaTime //adds the delta value of every tick
tick++ //add 1 to this value every tick (counts ticks)
disp=$time //copy time value for status
disp=ROUND($disp) //rounds status copy down for display
status "$disp seconds & $tick ticks"

1.3 Decoration Script — `DecorationName.script`

Auto-runs when the named decoration is used and/or interacted with near the player.
Tip: Acts like a local trigger on that decoration.
Example Snippet:

// add example

1.4 Trigger Script — any `*.script`

Run via: In-world triggers referencing a script filename.
Example Snippet:

// add example

1.5 Terminal Script — any `*.script`

Run via: A terminal UI element calling a script by name.
Example Snippet:

// add example

1.6 Keybind Script — any `*.script`

Bind at runtime: bind <key> <script> / unbind <key>
Held-input pattern: End the bound script with map quickreturn <keep> to avoid input lock.
Example Snippet:

// add example

1.7 Tips

Topic	Details	Examples
Files & Locations	Drop your scripts in `Data/Scripts/*.script`
Map .scripts	Remember to name your map scripts exactly as your maps have been named!	NewMap.eem & NewMap.script
Decoration script	`DecorationName.script` runs when the decoration is interacted with or triggered by the player.
`Triggers`	Call any script by filename.	Assign these in the editor.
`Terminals`	Call any script by filename.	Assign these in the editor.
Line format	One command per line. Arguments separated by single spaces. Comments with `//` to end of line.	`var=1` `if var == 1 {` `status "hello world" 0` `} // notes`
Logic Flow	Top→bottom.	Some operations block until a time, fade, video end, or player input.
Console one‑liner	Prefix with `;` to run a single command while playing. Example: `;player teleport 1 2 3`
Keybinds	`bind <key> <script>` / `unbind <key>`. Key‑bound scripts can be held; end them with `map quickreturn` if you want continuous behavior without input lock.

1.8 Variables scopes & Lifetimes

Scope	Lifetime	What it does / Notes
Local (bare name)	Current script	Fast scratch values. Locals reset on map change or new game. Retrieved from saves.
`map.*`	While on this map	Resets when the map changes. Retrieved from saves.
`global.*`	Across maps and saves	Persists across maps. Retrieved from saves.
`db.*`	Persistent KV store	Saved in `Saves/db.txt`. Good for meta‑progress, options, achievements mirrors.

⠀

2) Math, Variables & Arrays (explained)

2.1 Operators

Symbol	Name	Example	What it does
`=`	Assignment	`a=10` · `b=$a`	Stores a value in a variable. Use `$` to read another variable.
`==`	Equal to	`if $a == 1 { ... }`	True when two numbers/strings are the same.
`!=`	Not equal	`if $a != 0 { ... }`	True when values differ.
`<`	Less / Greater	`if $hp < 10 { ... }`	Numeric comparisons.
`>`	Less / Greater	`if $hp < 10 { ... }`	Numeric comparisons.
`<=`	Less/Greater or equal	`if $score >= 100 { ... }`	Numeric comparisons with equality.
`>=`	Less/Greater or equal	`if $score >= 100 { ... }`	Numeric comparisons with equality.
`+=`	Add & assign	`timer+=3`	Adds to a variable in place.
`-=`	Subtract & assign	`x-=1`	Subtracts and stores.
`*=`	Multiply & assign	`x*=2`	Multiplies and stores.
`/=`	Divide & assign	`x/=4`	Divides and stores.
`%=`	Modulo & assign	`frame%=20`	Remainder wrap (great for looping counters).
`++`	Increment / Decrement	`i++` · `i--`	Adds or subtracts exactly 1.
`--`	Increment / Decrement	`i++` · `i--`	Adds or subtracts exactly 1.

Tip: Use %= to make timers/counters loop: loop+=1 ; loop%=60 gives a 0…59 heartbeat.

2.2 Built‑in numeric functions

These return a number. Use them on the right side of = or a compound op.

Function	Example	Meaning
`RANDOM(min,max)`	`r=RANDOM(-5,5)`	Returns a random number in the inclusive range `[min,max]`. Integers if inputs are ints; floats if inputs include decimals.
`POWER(x)`	`p=POWER($x)`	Power helper; used like a `pow(x)` in older scripts. Combine with other math for exponents.
`SQRT(x)`	`s=SQRT($x)`	Square root of `x`.
`ROUND(x)`	`n=ROUND($x)`	Rounds `x` to the nearest display‑friendly step (~0.1 granularity).
`ABS(x)`	`a=ABS($x)`	Absolute value (drops the sign).
`FLOOR(x)`	`f=FLOOR($x)`	Largest integer ≤ `x`.
`CEIL(x)`	`c=CEIL($x)`	Smallest integer ≥ `x`.
`CLAMP(x,min,max)`	`v=CLAMP($x,0,1)`	Constrains `x` to the `[min,max]` range.
`MIN(a,b)`	`m=MIN($a,$b)`	Smaller of two values.
`MAX(a,b)`	`M=MAX($a,$b)`	Larger of two values.
`SIN(x)`	`y=SIN($t)`	Sine of `x` (radians). Smooth periodic wave.
`COS(x)`	`y=COS($t)`	Cosine of `x` (radians).
`TAN(x)`	`y=TAN($t)`	Tangent of `x` (radians).
`ASIN(x)`	`a=ASIN($x)`	Arc‑sine (radians). Domain −1…1.
`ACOS(x)`	`a=ACOS($x)`	Arc‑cosine (radians). Domain −1…1.
`ATAN(x)`	`a=ATAN($x)`	Arc‑tangent (radians).
`ATAN2(y,x)`	`a=ATAN2($y,$x)`	Angle of vector `(x,y)` in radians; correct quadrant handling.

2.3 Reading & writing variables

Pattern Example What it does

Copy b=$a Copies the current value of a into b.

Scope read x=$map.counter Reads the map. scoped variable.

Scope write global.best=MAX($global.best,$score) Writes back to global..

Defaulting if $unset == 0 { ... } Unset vars read as 0 (engine logs when parsing fails).

2.4 Arrays (alpha 47+) - WIP SECTION, haven’t validated

Feature Example What it does

Index by number map.path[$i]=42 Uses numeric index (can be negative).

Index by string db.stats["headshots"]=7 Uses string key (quote strings).

Nesting grid[$x][$y][$z]=1 Any depth (ragged arrays supported).

Read v=$db.stats["kills"][7] Retrieves stored value (0 if unset).

Modify in place counts[$k]+=1 Works with compound operations.

Mix keys a[-10]["k"][$i]+=3 Numeric and string keys can be mixed.

Notes: Arrays auto‑create as you assign; there’s no pre‑declare. Keep keys consistent (don’t mix numbers/strings for the same logical slot unless intentional).

2.5 Common patterns
//examples go here









//
⠀

3) Conditions, Blocks & Procedures

Operation Syntax What it does Blocks?

If if $v == 1 { ... } else { ... } Conditional execution. Comparators: == != <= >= < >. Whitespace matters. No

Else if $v == 1 { ... } else { ... } Conditional execution. Comparators: == != <= >= < >. Whitespace matters. No

Procedure procedure name ... end then call name Reusable block defined in the same file. No (until operations inside block)

Auto auto 0 | 1 Toggles automatic line advance. Useful in VN‑style scripts. No

Pause pause Waits for click or use input. Yes until input

Timeout timeout <seconds> Waits the given time. Yes for <seconds>

Halt halt Stops the current script immediately. N/A

keeptrigger keeptrigger Keeps the invoking trigger from auto‑deleting. No

bind bind <key> <script> / unbind <key> Creates/removes keybound scripts usable during play. No

unbind bind <key> <script> / unbind <key> Creates/removes keybound scripts usable during play. No

cheat cheat <code> <script> Binds a typed cheat code to run a script. No

⠀

4) Map Flow & Looping

Command Syntax What it does Blocks?

Start map start [keepmusic] Ends a cutscene/script and begins gameplay. keepmusic 1 preserves current music. No

Next map next / map goto <index> Moves to next map or a specific map by index. No

Goto map next / map goto <index> Moves to next map or a specific map by index. No

Return map return [0 | 1 | 2 | 3] Returns control and decides which sounds to keep: 0 none, 1 music, 2 music+SFX, 3 scripted SFX. No

Quickreturn map quickreturn [0 | 1 | 2 | 3] Same as return but does not lock input; ideal for held keybinds. No

Loop script <MapName>_loop.script Runs continuously while the map is active. Keep work cheap. N/A

Auto insert (implicit) In 1.11, if you omit, engine auto‑adds map start or map return 2. —

⠀

5) Player Commands (selected)

Area Syntax What it does Blocks?

Speed & Bob player speed <v> · player bobspeed <v> Sets move speed and overrides viewbob speed. Use bobspeed after speed. No

Movement player velocity set <x> <y> <z> · player velocity add <x> <y> <z> Sets or adds to player velocity directly. No

Teleport player teleport <x> <y> <z> [relative 0 | 1] Teleports to coords, or by offset when relative 1. No

Rotation & Turn player rotation <x> <y> · player turn 0 | 1 Sets look pitch/yaw. turn 1 locks mouse/strafe and disables tilt. No

Cam speed player camspeed <x> <y> Per‑axis camera turn speed. Also affects keyboard turning when player turn 1. No

Jump/Crouch player canjump 0 | 1 · player cancrouch 0 | 1 · player jumpheight <v> Enables or disables, adjusts jump arc height. No

Heights player height walk <v> · player height crouch <v> Sets standing and crouch camera height. No

Misc player steps 0 | 1 · player retro 0 | 1 · player weapon draw [slot] Toggles footstep SFX, retro camera, forces a weapon out. No

Player Checks

Check Syntax What it does

HP player check hp <var> Sets <var> to the player’s current health.

Max HP player check maxhp <var> Sets <var> to the player’s max health.

Armour player check armour <var> Sets <var> to the player’s current armour.

Max Armour player check maxarmour <var> Sets <var> to the player’s max armour.

Key player check key <n> <var> Sets <var> to 1 or 0, indicating if the player has key <n>.

Weapon player check weapon <slot> <var> Sets <var> to 1 or 0, indicating if the player has weapon <slot>.

Held Weapon player check heldweapon <var> Sets <var> to the currently selected weapon slot.

Ammo player check ammo <slot> <var> Sets <var> to the total amount of ammo in weapon <slot>.

Mag player check mag <slot> <var> Sets <var> to the amount of ammo in weapon <slot>'s magazine.

Position player check position <vx> <vy> <vz> Sets variables to the player’s current position.

Rotation player check rotation <vx> <vy> Sets variables to the player’s current rotation. (Alpha 47: rotation is no longer +90 offset.)

Aim Tile player check aimtile <tx> <ty> <tz> Sets variables to the tile under the crosshair, or −1 when none.

Flashlight

Command Syntax What it does

State/Lock flashlight state 0 | 1 · flashlight lock 0 | 1 Turns flashlight on/off and locks input toggle.

Range/Colour flashlight range <v> · flashlight colour <r> <g> <b> Adjusts reach and color.

Radius flashlight radius <v> Cone size.

⠀

6) World, Entities, Doors, Lights

Area Syntax What it does Notes

Entity spawn entity spawn tile <ent> <x> <y> <z> <rot> Spawns in the middle of a tile. Replaces older spawnat.

entity spawn precise <ent> <x> <y> <z> <rot> Spawns at exact fractional tile coords. e.g., 13.2 14.5 12.9

entity spawn relative <ent> <x> <y> <z> <rot> Spawns at an offset relative to invoker/player. Good for pickups, effects.

Doors door open [restoreClosing 0 | 1] Forces a door to open. Optional flag restores default closing behavior.

Lights (env) light ambient <r> <g> <b> <a> · light sun colour <r> <g> <b> <a> Adjusts ambient and sun color/alpha.

Sun direction light sun direction <x> <y> <z> Sets directional light vector.

Light offset light offset <x> <y> <z> Moves a light without changing its tile (avoids full recompute).

⠀

7) HUD & Menus

Command Syntax What it does Blocks?

HUD text hud text <name> <string> <size> <x> <y> <r> <g> <b> <layer> Draws or updates labeled text. No

HUD image/mask hud image <name> <path> <x> <y> <layer> · hud mask <name> <path> <x> <y> <layer> Draws images; masks affect images on the same layer. No

Transform hud rotate <name> <deg> · hud scale <name> <sx> <sy> · hud origin <name> <ox> <oy> Rotates, scales, or changes transform origin in pixels. No

Autoscale hud autoscale <name> stretch | width | height | off Auto‑fits to screen or by dimension. No

Toggle all hud active 0 | 1 Shows or hides all HUD elements. No

Menu widgets minput <x> <y> <script> <page> · mrange <x> <y> <db.var> <min> <max> <step> <def> <page> · mcheckbox <x> <y> <db.var> <0/1> <page> Build configurable menus, binding to db.* variables or scripts. No

Menu style mcheckboxstyle "Off" "Hover Off" "Hover On" "On" Customizes checkbox text. No

Status align (HUD configurator) Left/center alignment without editing hud.dat. —

⠀

8) VN Operations (Visual Novel)

Operation Syntax What it does Blocks?

Dialogue text "..." [r] [g] [b] [charsPerSecond] Shows dialog text. Optional color and speed. Yes until input

Font font <name> <size> Sets dialog font for subsequent text. No

Register image image <alias> <path> Preloads an image with an alias. No

Background bg <path> Sets background image. No

Show/Hide show <alias> <x> <y> <fadeSec> · hide <alias> <fadeSec> Fades images in/out. Yes for fade duration

Move move <alias> <x> <y> <sec> Tweens an image. Yes for duration

Layering front <alias> · back <alias> Brings image to front/back. No

Buttons button <id> <label> · label <id> Adds button and jump target; waits for click. Yes at choice

Audio play sound <name> [vol] [pan] · play music <path> [vol] [pan] Plays audio. Pan works with mono sounds. No

Video wait timeout video Waits until current video completes. Yes until end

Tip: Use 0 durations on show/hide/move for instant transitions without blocking.

⠀

9) Shaders & Post

Command Syntax What it does

Texture shader texture <uniform> <Path/To/Texture.png> Binds a texture to a shader uniform.

Uniforms shader bool\ | int\ | float\ | vec2\ | vec3\ | vec4 <uniform> <...> Sets shader uniform variables.

Config (ini) alphablendmode = 0 | 1 | 2 0 legacy, 1 multi‑pass blending, 2 no blending. Use 1 or 2 if entities vanish behind transparent tiles.

10) Settings & System

Command Syntax What it does

Render scale settings set scale <v> Sets internal render scale.

Resolution check settings check resolution <x> <y> Tests if the resolution is supported.

Time scale settings check timescale <var> · settings set timescale <v> Reads/sets global time scale. Affects gameplay and audio speed.

Quit quit Immediately exits the game.

⠀

11) Steam Integration

Purpose Syntax What it does

Unlock/Lock steam achievement unlock <api> · steam achievement lock <api> Unlocks or re‑locks an achievement.

Check achieve steam achievement check <api> <outVar> Writes 0 or 1 to <outVar> for locked/unlocked.

Stats steam stat check <api> <outVar> · steam stat set <api> <v> · steam stat increment <api> <v> Reads, writes, or increments a stat.

Testing (file) steam_appid.txt in exe folder Test locally. Non‑Steam builds: safe to delete steam_api.dll.

⠀

12) Sequences (Animator)

Operation Syntax What it does

Start sequence sequence start <name> Loads and plays Sequences/<name>.seq.

⠀

13) Breaking & Behavior Changes

Area Change Action needed

Rotation check player check rotation no longer adds +90 degrees (alpha 47) Remove manual offsets.

CHECKPOS Y value is no longer negative (alpha 45) Remove manual sign inversion.

Locals Locals reset on map change/new game (alpha 50) Don’t rely on leakage.

Script end Engine auto‑adds map start or map return 2 if omitted (alpha 23) Be explicit if you need different sound‑keep.

Deco access Active/scripted decorations accessible above/below (alpha 47) Verify vertical trigger logic.

⠀

14) Recipe Examples

A) Timer loop without deltaTime
loopTimer+=1
loopTimer%=512
if $loopTimer > 384 {
  status "Hello World!"
} else {
  status ""
}
B) Zoom shake
shakeTick+=1
shakeTick%=2
if $shakeTick == 0  {
target=RANDOM(-15,15)
}
zoomDelta=$target
zoomDelta-=$currentZoom
zoomDelta/=4
currentZoom+=$zoomDelta
player zoom $currentZoom
⠀

15) Troubleshooting

Symptom Likely Cause Fix

if never firing Spacing or brace style Use if $a == 1 { with spaces; keep { on the same line.

Key holds spam doors/map Held keybind ends with plain map return End with map quickreturn to keep inputs responsive.

Rotation math wrong Relied on +90 offset or negative Y Adjust for alpha 45 and 47 changes.

Loop hitches Heavy logic in <MapName>_loop.script Throttle with counters and modulo.

Variables “become 0” Forgot $ when reading a var Engine logs and substitutes 0; add $.

⠀

Addendum — Merge on 2025-10-01

Map Flow & Looping

Loop timing with $global.deltaTime

global.deltaTime equals 1 / loop-ticks-per-second.

At ~60 FPS, the loop script typically runs ~60 times/sec, so $global.deltaTime ≈ 1/60.

Use it for frame‑rate‑independent timers, lerps, and durations.

Accumulator example (1 unit per real second):
var += $global.deltaTime
Simple timer pattern (script sets the timer; loop consumes it):
//example
Note: The loop tick rate is capped by FPS and may also be limited by the optional loop frequency cap (see above). Use $global.deltaTime to normalize time‑based logic.

Loop script frequency cap (Alpha 53)
A new game config option limits how often the <MapName>_loop.script ticks.

0 = unlimited (still tied to FPS)

e.g., 20 = run up to 20 Hz
Note: Loop speed is always capped by the current FPS; this setting adds a lower cap and can aid in consistency of loop script logic

Settings & System

Game I/O

game save quick — manually overwrite the quicksave slot

game load quick — load from the quicksave slot

Entities

Compatibility note (older wiki examples):
Legacy docs/scripts may use:

entity spawnat <ent> <tileX> <tileY> <tileZ> <rot>

entity spawnatpos <ent> <X> <Y> <Z>
Prefer the newer forms: entity spawn tile|precise|relative ...

⠀

Appendix — Patterns & Idioms

Frame‑rate‑independent timer (using $global.deltaTime)

Use this when you want an action to fire after a real‑time delay, regardless of frame rate or loop tick rate.

Setup the timer in a script (or FSM equivalent):
// example
Consume the timer in <MapName>_loop.script:
// example
Notes

$global.deltaTime ≈ 1 / loopTicksPerSecond (≈ 1/60 at ~60fps).

Loop ticks are capped by FPS and may also be limited by the optional loop frequency cap; using deltaTime keeps timing consistent.

Reset global.timer to a concrete value (e.g., 5) when you want to arm the timer again.

Personal EFPSE Scripting Reference

1) Script Types & Entry Points

1.1 Map Script — `MapName.script`

1.2 Map Loop Script — `MapName_loop.script`

1.3 Decoration Script — `DecorationName.script`

1.4 Trigger Script — any `*.script`

1.5 Terminal Script — any `*.script`

1.6 Keybind Script — any `*.script`

1.7 Tips

1.8 Variables scopes & Lifetimes

2) Math, Variables & Arrays (explained)

2.1 Operators

2.2 Built‑in numeric functions

2.3 Reading & writing variables

2.4 Arrays (alpha 47+) - WIP SECTION, haven’t validated

2.5 Common patterns

3) Conditions, Blocks & Procedures

4) Map Flow & Looping

5) Player Commands (selected)

6) World, Entities, Doors, Lights

7) HUD & Menus

8) VN Operations (Visual Novel)

9) Shaders & Post

10) Settings & System

11) Steam Integration

12) Sequences (Animator)

13) Breaking & Behavior Changes

14) Recipe Examples

15) Troubleshooting

Addendum — Merge on 2025-10-01

Map Flow & Looping

Loop timing with `$global.deltaTime`

Settings & System

Game I/O

Entities

Appendix — Patterns & Idioms

Frame‑rate‑independent timer (using `$global.deltaTime`)

Pattern	Example	What it does
Copy	`b=$a`	Copies the current value of `a` into `b`.
Scope read	`x=$map.counter`	Reads the `map.` scoped variable.
Scope write	`global.best=MAX($global.best,$score)`	Writes back to `global.`.
Defaulting	`if $unset == 0 { ... }`	Unset vars read as `0` (engine logs when parsing fails).

Feature	Example	What it does
Index by number	`map.path[$i]=42`	Uses numeric index (can be negative).
Index by string	`db.stats["headshots"]=7`	Uses string key (quote strings).
Nesting	`grid[$x][$y][$z]=1`	Any depth (ragged arrays supported).
Read	`v=$db.stats["kills"][7]`	Retrieves stored value (0 if unset).
Modify in place	`counts[$k]+=1`	Works with compound operations.
Mix keys	`a[-10]["k"][$i]+=3`	Numeric and string keys can be mixed.

Operation	Syntax	What it does	Blocks?
`If`	`if $v == 1 { ... } else { ... }`	Conditional execution. Comparators: `== != <= >= < >`. Whitespace matters.	No
`Else`	`if $v == 1 { ... } else { ... }`	Conditional execution. Comparators: `== != <= >= < >`. Whitespace matters.	No
Procedure	`procedure name ... end` then `call name`	Reusable block defined in the same file.	No (until operations inside block)
Auto	`auto 0 \| 1`	Toggles automatic line advance. Useful in VN‑style scripts.	No
Pause	`pause`	Waits for click or use input.	Yes until input
Timeout	`timeout <seconds>`	Waits the given time.	Yes for `<seconds>`
Halt	`halt`	Stops the current script immediately.	N/A
keeptrigger	`keeptrigger`	Keeps the invoking trigger from auto‑deleting.	No
`bind`	`bind <key> <script>` / `unbind <key>`	Creates/removes keybound scripts usable during play.	No
`unbind`	`bind <key> <script>` / `unbind <key>`	Creates/removes keybound scripts usable during play.	No
cheat	`cheat <code> <script>`	Binds a typed cheat code to run a script.	No

Command	Syntax	What it does	Blocks?
Start	`map start [keepmusic]`	Ends a cutscene/script and begins gameplay. `keepmusic 1` preserves current music.	No
`Next`	`map next` / `map goto <index>`	Moves to next map or a specific map by index.	No
`Goto`	`map next` / `map goto <index>`	Moves to next map or a specific map by index.	No
Return	`map return [0 \| 1 \| 2 \| 3]`	Returns control and decides which sounds to keep: 0 none, 1 music, 2 music+SFX, 3 scripted SFX.	No
Quickreturn	`map quickreturn [0 \| 1 \| 2 \| 3]`	Same as `return` but does not lock input; ideal for held keybinds.	No
Loop script	`<MapName>_loop.script`	Runs continuously while the map is active. Keep work cheap.	N/A
Auto insert	(implicit)	In 1.11, if you omit, engine auto‑adds `map start` or `map return 2`.	—

Area	Syntax	What it does	Blocks?
Speed & Bob	`player speed <v>` · `player bobspeed <v>`	Sets move speed and overrides viewbob speed. Use `bobspeed` after `speed`.	No
Movement	`player velocity set <x> <y> <z>` · `player velocity add <x> <y> <z>`	Sets or adds to player velocity directly.	No
Teleport	`player teleport <x> <y> <z> [relative 0 \| 1]`	Teleports to coords, or by offset when `relative 1`.	No
Rotation & Turn	`player rotation <x> <y>` · `player turn 0 \| 1`	Sets look pitch/yaw. `turn 1` locks mouse/strafe and disables tilt.	No
Cam speed	`player camspeed <x> <y>`	Per‑axis camera turn speed. Also affects keyboard turning when `player turn 1`.	No
Jump/Crouch	`player canjump 0 \| 1` · `player cancrouch 0 \| 1` · `player jumpheight <v>`	Enables or disables, adjusts jump arc height.	No
Heights	`player height walk <v>` · `player height crouch <v>`	Sets standing and crouch camera height.	No
Misc	`player steps 0 \| 1` · `player retro 0 \| 1` · `player weapon draw [slot]`	Toggles footstep SFX, retro camera, forces a weapon out.	No

Check	Syntax	What it does
HP	`player check hp <var>`	Sets `<var>` to the player’s current health.
Max HP	`player check maxhp <var>`	Sets `<var>` to the player’s max health.
Armour	`player check armour <var>`	Sets `<var>` to the player’s current armour.
Max Armour	`player check maxarmour <var>`	Sets `<var>` to the player’s max armour.
Key	`player check key <n> <var>`	Sets `<var>` to 1 or 0, indicating if the player has key `<n>`.
Weapon	`player check weapon <slot> <var>`	Sets `<var>` to 1 or 0, indicating if the player has weapon `<slot>`.
Held Weapon	`player check heldweapon <var>`	Sets `<var>` to the currently selected weapon slot.
Ammo	`player check ammo <slot> <var>`	Sets `<var>` to the total amount of ammo in weapon `<slot>`.
Mag	`player check mag <slot> <var>`	Sets `<var>` to the amount of ammo in weapon `<slot>`'s magazine.
Position	`player check position <vx> <vy> <vz>`	Sets variables to the player’s current position.
Rotation	`player check rotation <vx> <vy>`	Sets variables to the player’s current rotation. (Alpha 47: rotation is no longer +90 offset.)
Aim Tile	`player check aimtile <tx> <ty> <tz>`	Sets variables to the tile under the crosshair, or −1 when none.

Command	Syntax	What it does
State/Lock	`flashlight state 0 \| 1` · `flashlight lock 0 \| 1`	Turns flashlight on/off and locks input toggle.
Range/Colour	`flashlight range <v>` · `flashlight colour <r> <g> <b>`	Adjusts reach and color.
Radius	`flashlight radius <v>`	Cone size.

Area	Syntax	What it does	Notes
Entity spawn	`entity spawn tile <ent> <x> <y> <z> <rot>`	Spawns in the middle of a tile.	Replaces older `spawnat`.
	`entity spawn precise <ent> <x> <y> <z> <rot>`	Spawns at exact fractional tile coords.	e.g., `13.2 14.5 12.9`
	`entity spawn relative <ent> <x> <y> <z> <rot>`	Spawns at an offset relative to invoker/player.	Good for pickups, effects.
Doors	`door open [restoreClosing 0 \| 1]`	Forces a door to open. Optional flag restores default closing behavior.
Lights (env)	`light ambient <r> <g> <b> <a>` · `light sun colour <r> <g> <b> <a>`	Adjusts ambient and sun color/alpha.
Sun direction	`light sun direction <x> <y> <z>`	Sets directional light vector.
Light offset	`light offset <x> <y> <z>`	Moves a light without changing its tile (avoids full recompute).

Command	Syntax	What it does	Blocks?
HUD text	`hud text <name> <string> <size> <x> <y> <r> <g> <b> <layer>`	Draws or updates labeled text.	No
HUD image/mask	`hud image <name> <path> <x> <y> <layer>` · `hud mask <name> <path> <x> <y> <layer>`	Draws images; masks affect images on the same layer.	No
Transform	`hud rotate <name> <deg>` · `hud scale <name> <sx> <sy>` · `hud origin <name> <ox> <oy>`	Rotates, scales, or changes transform origin in pixels.	No
Autoscale	`hud autoscale <name> stretch \| width \| height \| off`	Auto‑fits to screen or by dimension.	No
Toggle all	`hud active 0 \| 1`	Shows or hides all HUD elements.	No
Menu widgets	`minput <x> <y> <script> <page>` · `mrange <x> <y> <db.var> <min> <max> <step> <def> <page>` · `mcheckbox <x> <y> <db.var> <0/1> <page>`	Build configurable menus, binding to `db.*` variables or scripts.	No
Menu style	`mcheckboxstyle "Off" "Hover Off" "Hover On" "On"`	Customizes checkbox text.	No
Status align	(HUD configurator)	Left/center alignment without editing `hud.dat`.	—

Operation	Syntax	What it does	Blocks?
Dialogue	`text "..." [r] [g] [b] [charsPerSecond]`	Shows dialog text. Optional color and speed.	Yes until input
Font	`font <name> <size>`	Sets dialog font for subsequent `text`.	No
Register image	`image <alias> <path>`	Preloads an image with an alias.	No
Background	`bg <path>`	Sets background image.	No
Show/Hide	`show <alias> <x> <y> <fadeSec>` · `hide <alias> <fadeSec>`	Fades images in/out.	Yes for fade duration
Move	`move <alias> <x> <y> <sec>`	Tweens an image.	Yes for duration
Layering	`front <alias>` · `back <alias>`	Brings image to front/back.	No
Buttons	`button <id> <label>` · `label <id>`	Adds button and jump target; waits for click.	Yes at choice
Audio	`play sound <name> [vol] [pan]` · `play music <path> [vol] [pan]`	Plays audio. Pan works with mono sounds.	No
Video wait	`timeout video`	Waits until current video completes.	Yes until end

Command	Syntax	What it does
Texture	`shader texture <uniform> <Path/To/Texture.png>`	Binds a texture to a shader uniform.
Uniforms	`shader bool\ \| int\ \| float\ \| vec2\ \| vec3\ \| vec4 <uniform> <...>`	Sets shader uniform variables.
Config (ini)	`alphablendmode = 0 \| 1 \| 2`	0 legacy, 1 multi‑pass blending, 2 no blending. Use 1 or 2 if entities vanish behind transparent tiles.

Command	Syntax	What it does
Render scale	`settings set scale <v>`	Sets internal render scale.
Resolution check	`settings check resolution <x> <y>`	Tests if the resolution is supported.
Time scale	`settings check timescale <var>` · `settings set timescale <v>`	Reads/sets global time scale. Affects gameplay and audio speed.
Quit	`quit`	Immediately exits the game.

Purpose	Syntax	What it does
Unlock/Lock	`steam achievement unlock <api>` · `steam achievement lock <api>`	Unlocks or re‑locks an achievement.
Check achieve	`steam achievement check <api> <outVar>`	Writes `0` or `1` to `<outVar>` for locked/unlocked.
Stats	`steam stat check <api> <outVar>` · `steam stat set <api> <v>` · `steam stat increment <api> <v>`	Reads, writes, or increments a stat.
Testing	(file) `steam_appid.txt` in exe folder	Test locally. Non‑Steam builds: safe to delete `steam_api.dll`.

Area	Change	Action needed
Rotation check	`player check rotation` no longer adds +90 degrees (alpha 47)	Remove manual offsets.
CHECKPOS	Y value is no longer negative (alpha 45)	Remove manual sign inversion.
Locals	Locals reset on map change/new game (alpha 50)	Don’t rely on leakage.
Script end	Engine auto‑adds `map start` or `map return 2` if omitted (alpha 23)	Be explicit if you need different sound‑keep.
Deco access	Active/scripted decorations accessible above/below (alpha 47)	Verify vertical trigger logic.

Symptom	Likely Cause	Fix
`if` never firing	Spacing or brace style	Use `if $a == 1 {` with spaces; keep `{` on the same line.
Key holds spam doors/map	Held keybind ends with plain `map return`	End with `map quickreturn` to keep inputs responsive.
Rotation math wrong	Relied on +90 offset or negative Y	Adjust for alpha 45 and 47 changes.
Loop hitches	Heavy logic in `<MapName>_loop.script`	Throttle with counters and modulo.
Variables “become 0”	Forgot `$` when reading a var	Engine logs and substitutes 0; add `$`.

Personal EFPSE Scripting Reference

1) Script Types & Entry Points

1.1 Map Script — MapName.script

1.2 Map Loop Script — MapName_loop.script

1.3 Decoration Script — DecorationName.script

1.4 Trigger Script — any *.script

1.5 Terminal Script — any *.script

1.6 Keybind Script — any *.script

1.7 Tips

1.8 Variables scopes & Lifetimes

2) Math, Variables & Arrays (explained)

2.1 Operators

2.2 Built‑in numeric functions

2.3 Reading & writing variables

2.4 Arrays (alpha 47+) - WIP SECTION, haven’t validated

2.5 Common patterns

3) Conditions, Blocks & Procedures

4) Map Flow & Looping

5) Player Commands (selected)

6) World, Entities, Doors, Lights

7) HUD & Menus

8) VN Operations (Visual Novel)

9) Shaders & Post

10) Settings & System

11) Steam Integration

12) Sequences (Animator)

13) Breaking & Behavior Changes

14) Recipe Examples

15) Troubleshooting

Addendum — Merge on 2025-10-01

Map Flow & Looping

Loop timing with $global.deltaTime

Settings & System

Game I/O

Entities

Appendix — Patterns & Idioms

Frame‑rate‑independent timer (using $global.deltaTime)

1.1 Map Script — `MapName.script`

1.2 Map Loop Script — `MapName_loop.script`

1.3 Decoration Script — `DecorationName.script`

1.4 Trigger Script — any `*.script`

1.5 Terminal Script — any `*.script`

1.6 Keybind Script — any `*.script`

Loop timing with `$global.deltaTime`

Frame‑rate‑independent timer (using `$global.deltaTime`)