pixelscript 0.5.5

Multi language scripting runtime
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

[![crates.io](https://img.shields.io/crates/v/pixelscript)](https://crates.io/crates/pixelscript)
[![docs.rs](https://docs.rs/pixelscript/badge.svg)](https://docs.rs/pixelscript)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/jordan-castro/pixelscript?style=social)](https://github.com/jordan-castro/pixelscript)

[![Discord](https://dcbadge.limes.pink/api/server/https://discord.gg/Ws8gp5wSev)](https://discord.gg/Ws8gp5wSev)

# 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.5.

## 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:
```bash
cargo add pixelscript
```

### FFI based

For using pixelscript via ffi, clone this repository and run:
```bash
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        | rquickjs              | QuickJS small library. Supports ES2023          |
<!-- | `kora`           | Kora              | korar                 | A 2js and 2wasm language. Maintained by EpochTech.  | -->
<!-- | `php`            | PHP               | PH7                   | Only supports v5.3 and the engine is not maintained anymore | -->
<!-- | `luajit`         | Lua               | mlua                  | Uses the same code as the `lua` feature | -->

## 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_time`  | Adds time functions for all languages. Similar to Python `time` module. | | -->
<!-- | `pxs_io`    | Adds `open`, `File`, `Directory`, `close`, `glob`.      | Requires `pxs_set_filereader`, `pxs_set_filewriter`, and `pxs_set_dirreader` | -->
<!-- | `pxs_os` | -->

### 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.
```c
#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);

    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 is still being implemented.

Made with ❤️ by [@epochtechgames](https://x.com/epochtechgames)