wip

Author: gajop

.gitignore

@@ -9,3 +9,4 @@ env/
 
 # don't track local (dev) file
 *.local
+*.code-workspace

development_notes.md

@@ -0,0 +1,86 @@
+# Development Notes
+
+This document outlines the architecture and development process for integrating native Rust code with the C++ engine.
+
+## Architecture
+
+The system consists of two main parts:
+
+1.  **C++ Engine (`spring-bar`):** The core engine written in C++.
+2.  **Native Rust Module (`SBC.sdd/native`):** A Rust library that extends the engine's functionality.
+
+Communication between these two parts is achieved through a native interface.
+
+### Native Interface
+
+The bridge between C++ and Rust is defined by the following key files:
+
+-   **C++ Side:**
+    -   `rts/Game/Rust/NativeInterface.h`: Defines the interface structs (`NativeInterfaceBridge` and `NativeInterface`) that Rust will interact with.
+    -   `rts/Game/Rust/RustSystem.h` / `rts/Game/Rust/RustSystem.cpp`: Implements the C++ side of the bridge, providing the actual functionality that the interface exposes.
+
+-   **Rust Side:**
+    -   `native/src/native_interface.rs`: Defines the Rust representation of the native interface, allowing Rust code to call the C++ functions.
+
+## Development Process
+
+To add a new function to the native interface (e.g., `MyNewFunction`):
+
+1.  **`NativeInterface.h`:**
+    -   Add the virtual function declaration to the `NativeInterfaceBridge` struct:
+        ```cpp
+        virtual void MyNewFunction(int arg1, float arg2) = 0;
+        ```
+    -   Add the corresponding function pointer type and member to the `NativeInterface` struct:
+        ```cpp
+        using MyNewFunction = void(*)(NativeInterface* ptr, int arg1, float arg2);
+        MyNewFunction f_MyNewFunction;
+        ```
+
+2.  **`RustSystem.h`:**
+    -   Add the public override declaration for the new function in the `RustSystem` class:
+        ```cpp
+        void MyNewFunction(int arg1, float arg2) override;
+        ```
+
+3.  **`RustSystem.cpp`:**
+    -   Implement the function:
+        ```cpp
+        void RustSystem::MyNewFunction(int arg1, float arg2) {
+            // Implementation here
+        }
+        ```
+    -   Add the function to the `m_NativeInterface` struct initialization:
+        ```cpp
+        .f_MyNewFunction = [](NativeInterface* ptr, int arg1, float arg2) {
+            return ptr->bridge->MyNewFunction(arg1, arg2);
+        },
+        ```
+
+4.  **`native_interface.rs`:**
+    -   Add the function signature to the `NativeInterfaceImpl` struct:
+        ```rust
+        f_MyNewFunction: extern "C" fn(ptr: *const NativeInterfaceImpl, arg1: i32, arg2: f32),
+        ```
+    -   Add the function to the `NativeInterface` trait:
+        ```rust
+        fn MyNewFunction(&self, arg1: i32, arg2: f32);
+        ```
+    -   Implement the function for the trait:
+        ```rust
+        fn MyNewFunction(&self, arg1: i32, arg2: f32) {
+            (self.f_MyNewFunction)(self as *const NativeInterfaceImpl, arg1, arg2)
+        }
+        ```
+
+5.  **Usage in Rust:**
+    -   You can now call `Spring.MyNewFunction(arg1, arg2)` from anywhere in the Rust code.
+
+## Build Process
+
+-   **C++ (`spring-bar`):** Build using the provided docker script: `./docker-build-v2/build.sh linux`.
+-   **Rust (`SBC.sdd/native`):** Build using `cargo build` in the `native` directory.
+
+## Porting from Lua
+
+Existing Lua implementations in `rts/Lua` serve as a reference when porting functionality to the native Rust module. The goal is to replicate the logic from the Lua files in Rust, using the newly created native interface functions.

dist_cfg/config.json

@@ -166,7 +166,7 @@
 
     {
       "package": {
-        "id": "dev-bar-engine",
+        "id": "dev-bar",
         "display": "Development (BAR Engine)"
       },
       "downloads": {
@@ -188,6 +188,30 @@
       }
     },
 
+    {
+      "package": {
+        "id": "dev-bar-dev",
+        "display": "Development (Dev BAR Engine)"
+      },
+      "downloads": {
+        "engines" : [ "local-build-v2" ]
+      },
+      "auto_start" : true,
+      "no_downloads" : true,
+      "load_dev_exts": false,
+      "launch": {
+        "game": "SpringBoard Core $VERSION",
+        "map": "sb_initial_blank_10x8",
+        "map_options": {
+          "new_map_x": 10,
+          "new_map_y": 8
+        },
+        "game_options": {
+          "MapSeed": 42
+        }
+      }
+    },
+
     {
       "package": {
         "id": "asset-download",

doc/native_interface/abi.md

@@ -0,0 +1,147 @@
+# Native Interface ABI Strategy (Revised)
+
+This document describes how the C++ engine and native modules negotiate compatibility, expose new features safely, and validate behavior as the Lua bridge is ported.
+
+## Semantic Versioning
+
+The native interface uses semantic versioning applied to the entire API surface:
+
+- **MAJOR** – incremented when we intentionally break compatibility (removing fields, changing semantics). Modules built against a different major version are rejected.
+- **MINOR** – incremented when we add functionality in a backward-compatible way (new functions, new struct fields appended). Older modules continue to run but cannot see the new entries.
+- **PATCH** – bug fixes or comment-only changes. No behavior change.
+
+Shared header constants:
+
+```c
+#define SPRING_NATIVE_ABI_MAJOR 1
+#define SPRING_NATIVE_ABI_MINOR 0
+#define SPRING_NATIVE_ABI_PATCH 0
+```
+
+Rust bindings (via `build.rs` or generated code) read the same numbers so both sides agree.
+
+## Initialization Handshake
+
+Compatibility is enforced in a single initialization call. The engine exports:
+
+```c
+struct NativeInterface;
+
+struct NativeInitParams {
+    uint16_t abi_major;
+    uint16_t abi_minor;
+    uint16_t abi_patch;
+    uint32_t engine_commits_number; // optional, parsed from SpringVersion::GetCommits()
+};
+
+typedef bool (*NativeModuleInitFn)(const NativeInterface* iface,
+                                   const NativeInitParams* params,
+                                   struct NativeModuleInfo* out_info);
+```
+
+Example engine loader:
+
+```c
+bool EngineLoadModule(NativeModuleInitFn initFn) {
+    NativeInitParams params;
+    params.abi_major = SPRING_NATIVE_ABI_MAJOR;
+    params.abi_minor = SPRING_NATIVE_ABI_MINOR;
+    params.abi_patch = SPRING_NATIVE_ABI_PATCH;
+    params.engine_commits_number = std::atoi(SpringVersion::GetCommits().c_str());
+
+    NativeModuleInfo info = {};
+    if (!initFn(&nativeInterface, &params, &info)) {
+        return false; // module rejected the engine
+    }
+
+    if (info.abi_major != SPRING_NATIVE_ABI_MAJOR)
+        return false;
+
+    if (info.abi_minor > SPRING_NATIVE_ABI_MINOR)
+        return false;
+
+    RegisterModule(info);
+    return true;
+}
+```
+- Requires `<cstdlib>` for `std::atoi`.
+
+The module reports its details through `NativeModuleInfo`:
+
+```c
+struct NativeModuleInfo {
+    const char* module_name;      // optional diagnostics
+    uint16_t abi_major;
+    uint16_t abi_minor;
+    uint16_t abi_patch;
+};
+```
+
+Once the handshake succeeds both sides know the shared MAJOR/MINOR numbers and can make decisions about optional features.
+
+## Function Tables
+
+Each domain (SyncedCtrl, MetalMap, etc.) exposes a struct of function pointers inside `NativeInterface`.
+
+Rules:
+
+1. New functions are appended to the end of the struct when MINOR increases.
+2. Existing functions keep their signature and semantics until MAJOR changes.
+3. The engine always zero-initialises the function table; missing functions appear as `nullptr`.
+4. Modules must null-check optional entries if they require features added after their own `abi_minor`.
+
+Example skeleton:
+
+```c
+struct NativeSyncedCtrl {
+    AddHeightMapFn add_height_map;        // since 1.0
+    SetHeightMapFn set_height_map;        // since 1.0
+    SetHeightMapFuncFn set_height_map_fn; // since 1.0
+
+    LevelHeightMapFn level_height_map;    // added in 1.1 (nullptr on 1.0)
+    AdjustHeightMapFn adjust_height_map;  // added in 1.1
+};
+```
+
+Usage:
+
+```c
+if (moduleInfo.abi_minor >= 1 && iface->synced_ctrl.level_height_map != nullptr) {
+    iface->synced_ctrl.level_height_map(&request);
+}
+```
+
+Because the engine knows the module’s `abi_minor`, it can also avoid calling back into functions the module never provided.
+
+## Struct Layouts and Arrays
+
+Data exchanged across the boundary stays POD:
+
+- Fixed-width integers (`uint32_t`, `int32_t`, etc.) and `float`/`double`.
+- Pointers combined with explicit lengths for arrays:
+  ```c
+  struct FloatArrayView {
+      const float* values;
+      uint32_t     length;
+  };
+  ```
+- Null-terminated UTF-8 strings where needed (`const char*`).
+
+When a struct grows, new fields are appended. The engine only writes fields that exist for the module’s negotiated MINOR version. Array shapes and helper structs live in the specification directory (`spec/README.md`).
+
+## Call-In / Call-Out Catalogue
+
+- **Call-ins (module → engine)**: the function tables described above. Modules call what they need, guarding `nullptr` for optional entries.
+- **Call-outs (engine → module)**: planned via callback tables returned in `NativeModuleInfo` when needed. They will follow the same semver rules (append-only while MINOR increases).
+
+## Hot Reload Workflow
+
+1. Engine unloads the previous shared library and loads the new one.
+2. `NativeModuleInitFn` runs again; if the module rejects the current ABI, reload aborts.
+3. The module updates its cached pointers to the `NativeInterface` tables.
+
+
+## Open Items
+
+- Decide on the machine-readable format (YAML/TOML/JSON) that will drive code generation.
+- Specify the callback table format once engine-driven call-outs are required.

doc/native_interface/spec/ConstCMD.md

@@ -0,0 +1,77 @@
+# ConstCMD API
+
+## Legacy Lua Behaviour
+`LuaConstCMD.cpp` populates the `CMD` table with:
+
+- Option bit flags (`CMD.OPT_*`).
+- State constants (move, fire, wait).
+- A bidirectional map between command names and numeric IDs (`CMD.ATTACK == 20`, `CMD[20] == "ATTACK"`).
+- Backwards-compatibility aliases (e.g. `CMD.DGUN` → `CMD.MANUALFIRE`).
+
+Lua expects these values to be immutable and available in both synced and unsynced environments.
+
+## Native Interface Design
+Expose the same data through a read-only C ABI so native modules can look up command identifiers without going through Lua.
+
+```c
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct NativeCmdLabeledValue {
+    const char* name;   // UTF-8, null-terminated
+    int32_t     value;  // option bit, state code, wait code, etc.
+};
+
+struct NativeCmdCommandEntry {
+    const char* name;   // e.g. "ATTACK"
+    int32_t     id;     // e.g. 20
+};
+
+struct NativeCmdAlias {
+    const char* alias;  // e.g. "DGUN"
+    int32_t     id;     // maps to command id
+};
+
+struct NativeConstCMD {
+    const struct NativeCmdLabeledValue* option_flags;   // OPT_* entries
+    size_t option_flags_len;
+
+    const struct NativeCmdLabeledValue* move_states;    // MOVESTATE_*
+    size_t move_states_len;
+
+    const struct NativeCmdLabeledValue* fire_states;    // FIRESTATE_*
+    size_t fire_states_len;
+
+    const struct NativeCmdLabeledValue* wait_codes;     // WAITCODE_*
+    size_t wait_codes_len;
+
+    const struct NativeCmdCommandEntry* commands;       // CMD.* identifiers
+    size_t commands_len;
+
+    const struct NativeCmdAlias* aliases;               // compatibility aliases
+    size_t aliases_len;
+
+    // Helper callbacks provided by the engine (fast lookups over generated tables)
+    int32_t (*id_from_name)(const struct NativeConstCMD* self, const char* name);
+    const char* (*name_from_id)(const struct NativeConstCMD* self, int32_t id);
+};
+
+// Returns a pointer to an immutable singleton owned by the engine.
+// The pointer remains valid for the lifetime of the process.
+typedef const struct NativeConstCMD* (*GetConstCMDFn)(void);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+```
+
+### Engine Responsibilities
+- Populate the arrays at initialization using the same source data as `LuaConstCMD.cpp` and keep them sorted by name for deterministic lookups.
+- Implement `id_from_name` / `name_from_id` as pure, thread-safe helpers (e.g. binary search over the sorted arrays).
+- Expose `GetConstCMDFn` from the `NativeInterface` (e.g. `iface->const_tables.get_cmd`).
+
+### Consumer Guidance
+- Treat all pointers as read-only; copy strings/values if mutability is required.
+- Cache the returned pointer if desired—no hot-reload updates are expected for constants.
+- Use the helpers for lookups rather than scanning arrays manually.