Psych Engine Logo
T-Bar Engine - Documentation

Loading NDLLs

Just like how Lua has the ability to access C functions using FFI, HScript brings over ".ndll" loading from Codename Engine.

Setting up an Ndll

Compiling an NDLL is similar to compiling a base haxe project, only you are just compiling a library instead. To get an explanation on how to compile a project into an ndll file, refer to Codename Crew's ndll example repository.

If you wanna rename the ndll output lib, go into "project/Build.xml" and change "ndllexample"` in the "NDLL_NAME" attribute.

Renaming an ndll

Here is a brief explanation on everything in the repository:

  • project/common/ExternalInterface.cpp - This is where all of your C++ code will go.
  • project/common/Utils.cpp - This is an optional class that can house your C++ backend functions.
  • project/include/Utils.h - This is where all of your C++ headers for "Utils.cpp" will go. So if you want to access the functions in Utils.cpp in another file through #include, you will need to define those functions here.
  • project/Build.xml - You can edit the name of the ndll here.

    • These are for Android ndlls only and can be ignored if you are making a desktop ndll.

  • android/build.gradle - Specify dependencies and other stuff for Android ndlls.
  • android/src/main/java/org/haxe/extension/NdllExample.java - This is where all of your Java code will go for Android ndlls.

    • Of course, you are not just limited to these files. Your ndll project can contain as many code files as you need, these are just the starting files for simple stuff.

    There are also defines that you can use to make your ndll compatible with multiple platforms, here are the defines:

  • HX_WINDOWS - If the target is for Windows.
  • HX_MACOS - If the target is for MacOS.
  • HX_LINUX - If the target is for Linux.
  • HX_ANDROID - If the target is for Android.
  • IPHONE - If the target is for IPhone.

    • Compiling an Ndll

    Once you're ready to compile your project into an ndll, you just open up a command prompt/terminal and run the command "lime . rebuild [system name]".

    Here is a list of the available commands:

  • lime . rebuild windows - Compiles ndll to windows.
  • lime . rebuild linux - Compiles ndll to linux.
  • lime . rebuild mac - Compiles ndll to macOS.
  • lime . rebuild android - Compiles ndll to Android devices.
  • lime . rebuild iphone - Compiles ndll to iPhone / IOS devices.

    • append "-32" to compile the ndll for 32bit systems and append "-debug" if you wanna compile a debug ndll.

    Your compiled ndll will be in "ndll/[Platform name]64/ndllexample-[Platform name].ndll" or "ndll/[Platform name]/ndllexample-[Platform name].ndll" if it's 32 bits.

    Loading an Ndll

    Once you have your ndll with your C++ functions, it's now usable in T-Bar Engine. For haxe scripts, you need to import the `backend.util.NdllUtil` class.

    Note: On versions under 2.0, you will need to import`backend.NdllUtil` instead. You can also use conditionals to make your script compatible with multiple versions.

    Loading an ndll

    Some things to note:

  • The first argument of `getFunction` is the ndll path. Using `Paths.ndll` will automatically start in the "ndlls" folder and append the "-[Platform name]" at the end of the file name. This extension is dependent on the build's target platform.
  • The second argument is the function name. Pretty straight forward.
  • The final argument is the number of arguments that the function has. If your function has no params, just use 0.

    Note: The limit for the number of arguments an external function can have is 25.

    • You can now use the variable as if it was any other function!

    Loading an ndll 2

    Another good tip is to refrain from using the "NdllUtil.getFunction" everytime you want to load the function, as getFunction is a bit memory expensive. It is recommended to load a variable with the function once and use that variable as a function.

    Ndll Resources

    Microsoft Win32 API

    NekoVM FFI Documentation

    Codename Crew's Example Ndll

    hxcpp Github Repo

    hxcpp: CFFI Exposed Functions

    hxcpp: Example Ndll