Examples

Troubleshooting

What the error messages mean, why a script might do nothing, and where things are kept.

Start in the Scripts tab: the row's chip says on, off or error, and the output panel under the list shows everything the script printed and every error with its traceback.

#My script does nothing

Go through these in order:

Is it listed? A file added while the game runs shows up after rescan. The file must end in .lua.
Is the chip on? off means switched off; error means it stopped - read the output panel, fix, press reload.
Did it say anything? Add print( "loaded" ) at the top. If that line never appears, the file did not load; if it does, the handlers are the question.
Is the handler registered? on( "frame", ... ) has to run at the top level, not inside another function that never gets called.
Is the thing it needs there? ents.local_pawn() is nil on the main menu and while you are dead; move does not run while you are dead. Guard for nil and print what you get.
Is it drawn off-screen or under something? Draw a bright rectangle at 20, 20 first, to see that the canvas works, then build up.

#Error messages

#Raised by the runtime

Message	What it means
`script ran past its time budget`	A handler (or the file while loading) took longer than its allowance - about 30 ms for handlers, 2 s for loading. Look for a loop that does not end or work that belongs outside a per-frame handler.
`unknown event 'x'`	`on()` was given a name that is not an event. See the list; game events need the `game:` prefix.
`X is only available to trusted scripts - turn on 'trusted' for this script in the scripts tab`	The call needs the trusted flag.
`this canvas is only valid inside the callback that received it`	A canvas was kept in a variable and used later. Draw only inside `frame` or a control's `draw`.
`this command is only valid inside the move handler that received it`	The same for `cmd`.
`this view is only valid inside the view event that received it`	The same for the `view` object.
`this event is only valid inside the handler that received it`	The same for a game event's `ev`.
`this esp object is only valid inside the esp event that received it`	The same for `esp`.
`toggle: controls with a hotkey are created at load, or in a frame, menu, esp or timer handler`	`g:toggle()` was called from a game-thread handler such as `move`. Create it at load.
`game.particle can only be called from a move, stage or game event handler`	Particles are made on the game's thread.
`store.set: the value cannot be saved ...`	The value holds a function, userdata or a cycle.
`bad module name` / `module 'x' not found in scripts/lib, scripts/ or the script's folder`	`require` takes plain identifiers and looks in three places.

#Argument errors

Lua reports a wrong argument like bad argument #2 to 'text' (number expected, got nil). The number counts the self of a method call too: for canvas:text( x, y, ... ) the canvas is argument 1 and x is argument 2. A very common cause is an entity method that answered nil because the entity is gone - check before you use the result.

#Answers that are not errors

Several calls do not raise an error when something is missing; they answer nil and a message instead, so a script can carry on. Read the second value when you need to know why:

render.font, render.texture, render.gif, render.svg (cannot read the file) - fs.read (path outside the folder, no such file) - json.decode, json.encode, base64.decode - cheat.get, cheat.set (no such setting, wrong type) - ent:prop (no such field) - net.get, net.post (could not start).

#Problems with controls

A control forgot its value. Values are stored under the tab, the group's title and the control's label. Changing any of the three - or reordering two controls with the same label - starts that control again from its default. See Saving.

To reset a script's saved values, switch it off, delete C:\elysium\scripts\.data\<name>.values.json (and <name>.store.json for store), and switch it on.

A drop-down shows old entries after c:items(). It is closed on the next frame; open it again.

A toggle's hotkey does not work. Hotkeys of script toggles follow the same rules as the cheat's own: a key bound to a mouse button is ignored while the menu is open.

#Problems with drawing

Text is invisible. The colour's alpha is 0, or the text is drawn off the screen, or a clip is still open. Draw it at 20, 20 in white first.

A font or image does not appear for the first frame or two. They are built when first drawn; font:ready() and texture:ready() say when. Drawing something not ready is harmless.

A shader draws plain white. It is not compiled yet - check s:ready() - or it failed: s:error() has the message, and so has the output panel.

Things I drew are covered by the cheat's menu. That is the default: mid is below the menu. Use canvas:layer( "front" ).

#Where things are

What	Where
Scripts	`C:\elysium\scripts\*.lua`
A script's own files	`C:\elysium\scripts\<name>\`
On / off and trusted flags	`C:\elysium\scripts\.data\state.json`
Control values	`C:\elysium\scripts\.data\<name>.values.json`
`store`	`C:\elysium\scripts\.data\<name>.store.json`
Shared modules	`C:\elysium\scripts\lib\`

#Limits to know about

File names should be ASCII.
Only numbers and players can be read from a game event, not text fields.
A shader's parameters are per frame, not per draw call.
game.particle and a few engine calls belong to the game's thread.
Scripts cannot call each other or see each other's variables.
State does not survive a reload, apart from controls and store.