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.

Angles: All trig functions take/return radians. To get a 0…1 wave over time:
t+=0.1 ; wave=(SIN($t)+1)/2

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.