# Gotchas
A list of headaches that I've run into while using this library. Some could be changed, but no promise.

## General
- The first argument in every function call is the runtime it is currently in.
    - This means that function args should be using 1 based index. It's also easy to write a helper function of `get_arg = (args, idx) -> args[idx + 1]`.
- Maps are `pxs_Var` => `pxs_Var` typed.
    - Valid Keys
        - Int64
        - UInt64
        - Float64
        - Bool
        - String
    - Any non valid key will return a `pxs_Exception`.
- Passing `pxs_Object` around runtimes is UB.
    - To implement something similar it's best to implement a custom wrapper system. If the object comes from a `pxs_HostObject` you can recreate the host and 
    pass it into the language. `pxs_Factory` can also be used here for this. So your options are:
    - Custom wrapper system in your host language.
    - Recreate the `pxs_HostObject`.
    - Pass a `pxs_Factory`.
- `pxs_HostObject` Does not support inheritance.
- `async`/`await` is not supported in scripts. Handle that in the host language.

## Lua (lua5.5)
- A empty Table is interpreted as a `pxs_Object` not a `pxs_List`

## Python (pocketpy)
- When running `pxs_call` it will go through a checklist until the function is found BY NAME.
    - builtins 
    - current module
    - __main__ module
- When a `pxs_Object` or `pxs_Function` is off the stack and is dropped by pxs. It fails becuase it returns None via `_pxs_register`.

## JS (quickjs)
- PixelScript does not support returning `undefined`. The only way to do it would be to define a function for JS that returns `undefined`. And use that via 
`pxs_call`. But Python or Lua don't have `undefined`. Python does have `nil` but it would crash the program. So no `undefined` support. For most cases just
use `null`.
- `__pxs__` is a predefined name.
- When you call `pxs_compile` for JS code, it will be executed once to fincd the __pxs__ function. Keep that in mind!
- You should call `clearstate` before calling `stopthread`.
- In general when working with JS and threads it is a trial and error to get it working just right. But it does work! I got it working in [Pixel Ai Dash](https://play.google.com/store/apps/details?id=us.epochtech.pixelaidash&hl=es_CR). Just be patient. Although as a general rule when you add JS you have to be more `explicit` in how memory works. When to clear the state, when to start/stop a thread, etc.
- `pxs_Module`s can not be redefined. It won't crash but it will skip any redefined module names.
- In Javascript `pxs_exec` runs in its own module everytime. To make something global, you have to use `globalThis`.