Pixel Script

A multi language scripting runtime built in Rust.

PixelScript lets you expose the same API to multiple different languages in your program. Because it compiles to a C library, you can use it anywhere.

Why PixelScript?

Because most games pick only one language for scripting. PixelScript gives modders and scripters a choice:

• Performance? Go with Lua.
• Data/science/prototyping? Choose Python.
• Web developers? You got JavaScript.

Each language runtime uses the same PixelScript bindings.

Version

pixelscript crate is currently at version 0.5.1.

How to use

pixelscript can be used within a rust application or via ffi.

Rust based

For rust based (i.e. using this library inside a rust application) you can add it with cargo:

cargo add pixelscript

FFI based

For using pixelscript via ffi, clone this repository and run:

python scripts/build.py

This will build the project and place the necessary static libraries in a /pxsb folder. It will also generate a pixelscript.h C header file.

Supported languages

Feature flag	Language	Engine	Notes
lua	Lua	mlua	Fast, battle tested, v5.4
python	Python	pocketpy V2.1.8	Requires MSVC on Windows
js	JavaScript	ejr	easy javascript runtime
php	PHP	PH7	Only supports v5.3 and the engine is not maintained anymore

CoreLib

To include the PixelScript core API, add the include-core feature. Or include the specific modules as feature tags.

Module name	Module purpose	Notes
pxs_json	Adds encode/decode functions for all languages.

pxs_json

Overview of what is incldued in pxs_json module.

Name	Type	Doc Comment
encode	Function	Encodes a object into a JSON string.
decode	Function	Decodes a JSON string into a language object

Example

Here is a "Hello World" example supporting Lua, Python, JavaScript and PHP.

#include "pixelscript.h"

// One without the macro
pxs_VarT println(pxs_VarT args) {
    // Get contents (0 is always Runtime)
    pxs_VarT contents_var = pxs_listget(args, 1);
    char* contents_str = pxs_getstring(contents_var);

    printf("%s", contents_str);

    // Free the string
    pxs_freestr(contents_str);
}

int main() {
    pxs_initialize();
    
    // Create a module
    pxs_Module* main = pxs_newmod("main");

    // Add callbacks
    pxs_addfunc(main, "println", println, NULL);

    // Lua
    const char* lua_script = "local main = require('main')\n"
        "main.println('Hello World from Lua!')";
    char* error = pxs_exec(pxs_Lua, lua_script, "<ctest>");
    pxs_freestr(error);

    // Python
    const char* python_script = "import main\n"
                                "main.println('Hello World from Python')\n";

    char* error = pxs_execpython(pxs_Python, python_script, "<ctest>");
    pxs_freestr(error);

    // JavaScript
    const char* js_script = "import * as main from 'main';\n"
                            "main.println('Hello World from JavaScript!');";
    char* error = pxs_execjs(pxs_JavaScript, js_script, "<ctest>");
    pxs_freestr(error);

    // PHP!!!! 
    const char* php_script = "include('main');\n" // or require
                            "\\main\\println('Hello World from PHP!');";
    char* error = pxs_execphp(pxs_PHP, php_script, "<ctest>");
    pxs_freestr(error);

    pxs_finalize();

    return 0;
}

Used in

• Pixel Ai Dash

Future

This will ideally be used by all future epochtech games since it allows for modding in multiple languages. It's not quite ready to be used in production for anyone other than myself and epochtech. But if you make PRs to fix something or open issues, I will be responding and merging. Feel free to add a language, just check out /lua or /python for examples on how to use Var, Func, Module, PixelObject, and PixelScripting.

Note: JS and PHP are still being implemented.

Made with ❤️ by @epochtechgames