Script

A Script is a named, cached asset holding the function references parsed from a .lua file.
Scripts are loaded once into a fixed-size cache (max 256) and retrieved by name; a
Behavior is what actually runs one on a GameObject. For the shape of
that .lua file — the table it returns and the callbacks the engine looks for — see the
Scripting Model.

Static calls use the type table (Script.Create(...)); the one instance method uses colon syntax
on a handle (script:ID()).

Types

Script — an opaque 8-byte handle (userdata) into the script cache. The handle encodes
cache_index + 1 in a Handle64 with a fixed generation of 1: scripts are append-only and never
recycled, so a handle stays valid for the life of the Lua state. tostring(script) yields
Script{name}, or the bare string Script if the entry cannot be resolved.

The safe test is Script.Exists (never raises). By contrast script:ID() runs check_handle,
which raises a Lua type error if called on a value that is not a Script userdata.

Creation & Destruction

Script.Create( string name, string filename ) : Script or nil
Loads the script at filename (resolved against the cache’s base directory) and registers it
under name. name and filename are read with luaL_checklstring, which coerces a number
to its decimal text (42 → "42"); only a non-string, non-number argument raises. Non-UTF-8 bytes
raise a Lua argument error. Returns nil if the cache pointer is unset (silent) or the file
fails to load (silent); if the cache is full it returns nil and prints [Script] Cache full… to
stderr.

Known issue: Script.Create is idempotent on name alone — if a script with that name is
already cached it returns the existing handle and ignores the new filename
(lua_script.rs:311). Registering two different files under one name is silently impossible; the
first load wins. There is also no Lua-side unload or replace (the cache is append-only, capacity
256); reloading from disk is a Rust-only path (ScriptCache::reload_all).

Script.Get( string name ) : Script or nil
Returns the handle for an already-loaded script name. name is read with luaL_checklstring,
which coerces a number to its decimal text; only a non-string, non-number value raises (as does
non-UTF-8). Returns nil — with no warning — if the cache is unset or no script by that
name is registered.

Script.Exists( Script script ) : boolean
The safe test. Returns false for a null pointer, any userdata whose length isn’t 8 bytes, or any
whose embedded type_id isn’t the Script id; otherwise checks that the cache slot is loaded. Never
raises — safe on null / wrong-type / unresolved handles.

Functions

script:ID( ) : string or nil
The script’s registered name. Raises a Lua type error if called on a non-Script value; returns
nil if the handle’s cache entry cannot be resolved.

Example

-- Load once at startup; look it up by name later.
local script = Script.Create("enemy", "scripts/enemy.lua")

-- ...elsewhere...
local same = Script.Get("enemy")
if Script.Exists(same) then
    print(same:ID())   -- "enemy"
end