NatinyScriptValue

typedef struct NatinyScriptValue {
    uint32_t type;
    uint64_t ref;
    union {
        bool     boolean;
        double   number;
        uint64_t handle;
        struct { const char* data; uint32_t size; } string;
    };
} NatinyScriptValue;

One value on its way between C and a script. Everything in the Script module that passes something either way passes this type - including a table and a function, which are values like any other.

Type tags

Tag	Field	Meaning
`NATINY_SCRIPT_NIL`	-	nothing; also what a missing name reads as
`NATINY_SCRIPT_BOOL`	`boolean`	`true` or `false`
`NATINY_SCRIPT_NUMBER`	`number`	a Lua number
`NATINY_SCRIPT_STRING`	`string.data`, `string.size`	bytes, not necessarily text
`NATINY_SCRIPT_HANDLE`	`handle`	an engine handle; reaches the script as a number
`NATINY_SCRIPT_TABLE`	-	a table living in the script
`NATINY_SCRIPT_FUNCTION`	-	a function living in the script

ref belongs to natiny. It is what a table, a function or a held string is reached through, and a value is passed around whole rather than taken apart.

Example

NatinyScriptValue config = natiny_script_make_table(script);

natiny_script_table_set(script, config, "title",
                        natiny_script_make_string("Sponza"));
natiny_script_set(script, "game.config", config);

How long a value lasts

Everything a script hands out is borrowed. A string, a table or a function from natiny_script_get, a call's results, the table functions or natiny_script_make_table / natiny_script_make_function is valid until the next natiny_script_run, natiny_script_call or natiny_script_call_value on that script. There is nothing to destroy: a table is made, filled and given a name well inside that window, and after it the script is what keeps the table.
The next call ends the loan only after its arguments are on the stack, so a borrowed value can be passed straight into that call.
Arguments of a function made with natiny_script_make_function are valid until that function returns.
natiny_script_hold keeps any value past its loan, and natiny_script_release gives it back. A kept value is the one thing you release.
Numbers, booleans and handles are copies and last as long as you keep them.