Merge remote-tracking branch 'origin/main' into feat/ecs

Author: IllustrisJack

.gitignore

@@ -14,6 +14,7 @@
 .idea/
 .vs/
 .vscode/
+.zed/
 cmake-build-*/
 
 ## OS Junk files

Cargo.lock

@@ -6,6 +6,8 @@ Limit Theory Redux is a fork of the now-cancelled open world space simulation ga
 
 This repository continues the game and engine code from the second generation of LT's development, when all work was originally migrated to C/C++ and Lua, which we have since ported to Rust and Lua. For the older, C++/LTSL version of Limit Theory, see https://github.com/JoshParnell/ltheory-old.
 
+[Documentation](doc/README.md).
+
 ## Contributing to Limit Theory Redux
 See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
 

README.md

@@ -0,0 +1,12 @@
+# Limit Theory Redux documentation
+
+1. [Engine](engine/README.md)
+   - [Phx](../engine/lib/phx/README.md)
+   - [HmGui](../engine/lib/phx/src/ui/hmgui/README.md)
+   - [LuaJIT FFI](../engine/lib/luajit-ffi-gen/README.md)
+   - [Engine Workers](../engine/lib/phx/src/engine/task_queue/README.md)
+2. [Scripting](script/README.md)
+   - [Lua Workers](script/workers.md)
+   - [HmGui](../script/UI/HmGui/README.md)
+3. [Full structure](LTheory%20Full%20Restructure.md)
+4. [Control keys](GameControlKeys.txt)

docs/GameControlKeys.txt doc/GameControlKeys.txt

@@ -0,0 +1,6 @@
+# LTR Engine documentation
+
+1. [Phx](../../engine/lib/phx/README.md)
+2. [HmGui](../../engine/lib/phx/src/ui/hmgui/README.md)
+3. [LuaJIT FFI](../../engine/lib/luajit-ffi-gen/README.md)
+4. [Engine Workers](../../engine/lib/phx/src/engine/task_queue/README.md)

docs/LTheory Full Restructure.md doc/LTheory Full Restructure.md

@@ -0,0 +1,4 @@
+# LTR Scripting documentation
+
+1. [Lua Workers](workers.md)
+1. [HmGui](../../script/UI/HmGui/README.md)

doc/README.md

@@ -0,0 +1,27 @@
+# LTR Lua Workers
+
+Lua Worker is based on the engine worker and allows to run Lua code in the new Lua state in a separate thread.
+
+[TaskQueue](../../engine/lib/phx/script/meta/TaskQueue.lua)([ext](../../engine/lib/phx/script/ffi_ext/TaskQueue.lua)) object is used to create and manage workers. To send data between workers and main thread [Payload](../../engine/lib/phx/script/meta/Payload.lua) object is used.
+
+Steps to create a new worker and run it:
+1. Create a new worker function in a separate file, see [TestWorkerFunction](../../script/States/App/Tests/TestWorkerFunction.lua) for example.
+   - Use `WorkerFunction.Create()` to create a worker function. As an input parameter it accepts a callback function with a single input parameter that can be either a simple type (integer, string, etc.) or **Payload**, and that returns an optional output of the same type (simple or **Payload**).
+2. Create and run worker, see [WorkerTest](../../script/States/App/Tests/WorkerTest.lua) for example.
+   1. Create and start worker with a new worker type:
+        ```lua
+        local workerId = TaskQueue:startWorker("MyWorker", "MyWorkerFunction.lua", 1)
+        ```
+        It is possible to run multiple instances of the worker for load balancing purposes.
+        Creation of the worker adds new element to the `WorkerId` table: `WorkerId.MyWorker`.
+   2. To send message to the worker use `TaskQueue:sendTask()`:
+        ```lua
+        local taskId = TaskQueue:sendTask(workerId, payload)
+        ```
+   3. To read message from the worker:
+        ```lua
+        local taskId, payload = TaskQueue:nextTaskResult(workerId)
+        ```
+        If `taskId == nil` then worker queue doesn't have any output messages.
+    
+    In the main game loop send messages to corresponding workers and then check each frame for response from them.

doc/engine/README.md

@@ -19,6 +19,7 @@ luajit-ffi-gen.workspace = true
 # external crates
 arboard = "3.4"
 chrono = "0.4"
+cli-table = { version = "0.4", default-features = false }
 crossbeam = "0.8"
 directories = "5.0"
 flate2 = "1.0"

doc/script/README.md

@@ -2,10 +2,17 @@ local libphx = require('libphx').lib
 local PayloadConverter = require('Core.Util.PayloadConverter')
 
 function onDef_TaskQueue_t(t, mt)
-    mt.__index.startWorker = function(self, workerId, workerName, scriptPath, instancesCount)
+    mt.__index.startWorker = function(self, workerName, scriptPath, instancesCount)
+        -- TODO: fix this if possible
+        -- -@class WorkerId
+        -- -@field workerName integer
+        WorkerId.Register(workerName)
+
+        local workerId = WorkerId[workerName]
         if not libphx.TaskQueue_StartWorker(self, workerId, workerName, scriptPath, instancesCount) then
             Log.Error("Cannot start worker: " .. workerName)
         end
+        return workerId
     end
 
     mt.__index.sendTask = function(self, workerId, data)

doc/script/workers.md

@@ -4,7 +4,9 @@ function onDef_WorkerId(t, mt)
     ---@class WorkerId
     ---@field Register fun(workers: table<string>) Register a new worker types to the WorkerId table. Fail if worker already exists.
     t.Register = function(newWorkers)
-        if type(newWorkers) ~= 'table' then
+        if type(newWorkers) == 'string' then
+            newWorkers = { newWorkers }
+        elseif type(newWorkers) ~= 'table' then
             Log.Error("new workers should be in a table")
             return
         end

engine/bin/ltr/readme.md engine/bin/ltr/README.md

@@ -0,0 +1,44 @@
+-- AUTO GENERATED. DO NOT MODIFY!
+-- Profiler --------------------------------------------------------------------
+local Loader = {}
+
+function Loader.declareType()
+    return 0, 'Profiler'
+end
+
+function Loader.defineType()
+    local ffi = require('ffi')
+    local libphx = require('libphx').lib
+    local Profiler
+
+    do -- C Definitions
+        ffi.cdef [[
+            void Profiler_Enable     ();
+            void Profiler_Disable    ();
+            void Profiler_Begin      (cstr name);
+            void Profiler_End        ();
+            void Profiler_SetValue   (cstr name, int value);
+            void Profiler_LoopMarker ();
+            void Profiler_Backtrace  ();
+        ]]
+    end
+
+    do -- Global Symbol Table
+        Profiler = {
+            Enable     = libphx.Profiler_Enable,
+            Disable    = libphx.Profiler_Disable,
+            Begin      = libphx.Profiler_Begin,
+            End        = libphx.Profiler_End,
+            SetValue   = libphx.Profiler_SetValue,
+            LoopMarker = libphx.Profiler_LoopMarker,
+            Backtrace  = libphx.Profiler_Backtrace,
+        }
+
+        if onDef_Profiler then onDef_Profiler(Profiler, mt) end
+        Profiler = setmetatable(Profiler, mt)
+    end
+
+    return Profiler
+end
+
+return Loader

engine/lib/phx/Cargo.toml

@@ -17,25 +17,26 @@ function Loader.defineType()
 
     do -- C Definitions
         ffi.cdef [[
-            void       TimeStamp_Free          (TimeStamp*);
-            TimeStamp* TimeStamp_Now           ();
-            TimeStamp* TimeStamp_GetFuture     (double seconds);
-            double     TimeStamp_GetDifference (TimeStamp const*, TimeStamp const* endTime);
-            double     TimeStamp_GetElapsed    (TimeStamp const*);
-            double     TimeStamp_GetElapsedMs  (TimeStamp const*);
-            TimeStamp* TimeStamp_GetRelative   (TimeStamp const*, double seconds);
-            double     TimeStamp_ToDouble      (TimeStamp const*);
-            uint64     TimeStamp_ToSeconds     (TimeStamp const*);
+            void       TimeStamp_Free           (TimeStamp*);
+            TimeStamp* TimeStamp_Now            ();
+            TimeStamp* TimeStamp_GetFuture      (double seconds);
+            double     TimeStamp_GetDifference  (TimeStamp const*, TimeStamp const* endTime);
+            double     TimeStamp_GetElapsed     (TimeStamp const*);
+            double     TimeStamp_GetElapsedMs   (TimeStamp const*);
+            TimeStamp* TimeStamp_GetRelative    (TimeStamp const*, double seconds);
+            double     TimeStamp_ToDouble       (TimeStamp const*);
+            uint64     TimeStamp_ToSeconds      (TimeStamp const*);
+            uint32     TimeStamp_ToSubsecMillis (TimeStamp const*);
         ]]
     end
 
     do -- Global Symbol Table
         TimeStamp = {
-            Now           = function()
+            Now            = function()
                 local _instance = libphx.TimeStamp_Now()
                 return Core.ManagedObject(_instance, libphx.TimeStamp_Free)
             end,
-            GetFuture     = function(seconds)
+            GetFuture      = function(seconds)
                 local _instance = libphx.TimeStamp_GetFuture(seconds)
                 return Core.ManagedObject(_instance, libphx.TimeStamp_Free)
             end,
@@ -49,15 +50,16 @@ function Loader.defineType()
         local t  = ffi.typeof('TimeStamp')
         local mt = {
             __index = {
-                getDifference = libphx.TimeStamp_GetDifference,
-                getElapsed    = libphx.TimeStamp_GetElapsed,
-                getElapsedMs  = libphx.TimeStamp_GetElapsedMs,
-                getRelative   = function(self, seconds)
+                getDifference  = libphx.TimeStamp_GetDifference,
+                getElapsed     = libphx.TimeStamp_GetElapsed,
+                getElapsedMs   = libphx.TimeStamp_GetElapsedMs,
+                getRelative    = function(self, seconds)
                     local _instance = libphx.TimeStamp_GetRelative(self, seconds)
                     return Core.ManagedObject(_instance, libphx.TimeStamp_Free)
                 end,
-                toDouble      = libphx.TimeStamp_ToDouble,
-                toSeconds     = libphx.TimeStamp_ToSeconds,
+                toDouble       = libphx.TimeStamp_ToDouble,
+                toSeconds      = libphx.TimeStamp_ToSeconds,
+                toSubsecMillis = libphx.TimeStamp_ToSubsecMillis,
             },
         }
 

engine/lib/phx/script/ffi_common/Profiler.lua

@@ -0,0 +1,29 @@
+-- AUTO GENERATED. DO NOT MODIFY!
+---@meta
+
+---@class Profiler
+Profiler = {}
+
+-- Enables profiling and initializes the profiler state
+function Profiler.Enable() end
+
+-- Disables profiling and processes results
+function Profiler.Disable() end
+
+-- Starts a new profiling scope
+---@param name string
+function Profiler.Begin(name) end
+
+-- Ends the current profiling scope
+function Profiler.End() end
+
+---@param name string
+---@param value integer
+function Profiler.SetValue(name, value) end
+
+-- Records frame timing for each active scope
+function Profiler.LoopMarker() end
+
+-- Prints backtrace of active scopes
+function Profiler.Backtrace() end
+

engine/lib/phx/script/ffi_ext/TaskQueue.lua

@@ -8,11 +8,7 @@
 TaskQueue = {}
 
 -- Start Lua worker with provided script file.
----@param workerId integer
----@param workerName string
----@param scriptPath string
----@param instancesCount integer
----@return boolean
+---@overload fun(self: table, workerName: string, scriptPath: string, instancesCount: integer): integer
 function TaskQueue:startWorker(workerId, workerName, scriptPath, instancesCount) end
 
 -- Stop Lua worker and remove it from the queue.

engine/lib/phx/script/ffi_ext/WorkerId.lua

@@ -39,3 +39,7 @@ function TimeStamp:toDouble() end
 ---@return integer
 function TimeStamp:toSeconds() end
 
+-- Returns the fractional part in whole milliseconds.
+---@return integer
+function TimeStamp:toSubsecMillis() end
+

engine/lib/phx/script/ffi_gen/Profiler.lua

@@ -429,10 +429,10 @@ impl Engine {
     }
 
     pub fn update() {
+        Profiler::begin("Engine_Update");
         unsafe {
-            Profiler_Begin(c_str!("Engine_Update"));
             Metric_Reset();
-            Profiler_End();
         }
+        Profiler::end();
     }
 }