flecs-luajit

WIP single-file and pure Lua bindings for Flecs using the LuaJIT FFI. The aim is to implement at least all the basic Flecs' features that allow making a game. Unsafer operations are not implemented yet. Based on https://github.com/flecs-hub/flecs-lua/

How to build and run the tests

• Do a standard CMake build. This will automagically run utils/preprocess.(sh|bat) having the project root as the current working directory every time the Lua source or the Flecs header change. The script generates the FFI cdefs for Flecs from libs/flecs/flecs.h, appends src/ecs.lua and generates the final Lua file, ready to use, in distr/ecs.lua. In Windows, you need to have cl.exe available in your PATH. One way to do it is by executing it in a "Command Prompt for VS 20xx," available from the start menu. The output is equivalent to LuaJIT, but it is uglier. I wouldn't use it to generate the distribution Lua file that is to be committed.
• Download, compile and install LuaJIT following the directions in the official webpage, or just install it from your distro's package repositories, but I don't personally use those. For Windows, after compiling LuaJIT, copy or symlink lua51.lib found at luajit/src after the build to a new directory under this project's root libs/luajit. Copy lua.h, luaconf.h, lualib.h and lauxlib.h to a new directory libs/lua/luajit-2.1. Blame W*ndows for not having a standard way to install development libraries.
• When running the test program, make sure the distr/ecs.lua and src/tests.lua files are available in the current working directory. CMake takes care of this automatically (copies the files to the binary directory).

Embedding into another app

On the Lua side, you only need distr/ecs.lua, the standard Lua libraries, and the FFI, BitOp and string buffer LuaJIT libraries, all included with the latest LuaJIT commits. On the C side, your app needs to export Flecs' symbols, which *nix compilers do by default. For Windows, you need to comment out the second line #define flecs_STATIC in flecs.h and define flecs_EXPORTS, probably unless you use Flecs as a DLL, but I haven't tested this. Also, it's important to define FLECS_SOFT_ASSERT to make Flecs do some checks and allow for recoverable errors, specially if you run third-party code, like game mods! Finally, just run ecs.lua however you want. It returns the entire module as a table.

Configuration

When running utils/preprocess.sh, any arguments you pass will be forwarded to cc. Therefore, you are able to customize Flecs' macros. Notably, you can customize ecs_float_t and ecs_ftime_t to use double precision, for example with ./utils/preprocess.sh -Decs_ftime_t=double -Decs_float_t=double. You MUST make sure to preprocess and compile flecs.c with the same definitions, otherwise chaos will ensure!

Caveats

This library uses ffi.C.free() to release the memory allocated and returned by Flecs, so don't pass custom memory management functions to Flecs (for example, by using ecs_os_set_api())! This unsafe operation is not yet implemented.

TODO

• Ensure the library is more or less safe to expose to third-party code, like mods.
• Allow for custom ecs_os_api_t.