interoperability

api needs to facilitate easy interoperability with other languages and tools, for that certain considerations are taken:

number of public api calls is kept at the minimum
procedure parameters can only use basic types, no aggregates, with exception of Vec/Matrix types and alike, with no new additions, ever (see /include/twn_types.h)
enum types are allowed, as they decay to numeric type (but language-specific api can decide to provide simple ways to use them)
optionals can be expressed via pointer passage of value primitives, assumed immutable, with the NULL expressing default value
no opaque types, only keys if needed
pointers to pointers aren't allowed
when mutation on input is done, - it shouldn't be achieved by a mutable pointer, but the return value
return value could be a simple aggregate that is translatable to a dictionary of primitives
module prefix is used for namespacing, actual symbols come after the prefix (<module>_<symbol>)
symbols should not contain numerics at the start nor after the namespace prefix
32 bit floating point is the only numeric type
/include/twn_api.json file is hand-kept with a schema to aid automatic binding generation and tooling
parameter names should not collide with keywords of any language that is targetted; if so happens, parameter alias could be added
any procedure can't have more than 8 parameters