# that-sky-project/that-sky-engine architecture

> Architecture diagram of the GitHub repository that-sky-project/that-sky-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/that-sky-project/that-sky-engine
- Repository: https://github.com/that-sky-project/that-sky-engine

## Overview

That Sky Engine is a compatibility-oriented codebase for modules targeting Sky:CotL v0.32.2. The visible product workflow exposes reflected C++ classes to Lua: class bindings create Lua globals and callbacks, which use metadata to construct, inspect, cast, and delete objects. Object storage can come from a bounded heap, with an STL allocator fallback; the heap itself uses dlmalloc mspaces. The README gives no broader feature workflow, and source excerpts are partial, so this map focuses on these evidenced runtime responsibilities.

Main entry points: [`src/Code/Base/LuaInterface.cpp`](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Base/LuaInterface.cpp) (Lua bindings), [`src/Code/Memory/Heap.cpp`](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Memory/Heap.cpp) (Tagged heap), [`src/Code/Base/Meta.cpp`](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Base/Meta.cpp) (Metadata system), [`src/Code/Base/Meta.hpp`](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Base/Meta.hpp) (Metadata types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interop["Lua interoperability"]
  node_binding["Lua bindings<br/>[LuaInterface.cpp]"]
end

subgraph group_reflection["Runtime reflection"]
  node_meta["Metadata system<br/>[Meta.cpp]"]
  node_meta_api["Metadata types<br/>[Meta.hpp]"]
end

subgraph group_memory["Memory management"]
  node_heap["Tagged heap<br/>[Heap.cpp]"]
  node_heap_api["Heap interface<br/>[Heap.hpp]"]
  node_dlmalloc[("Mspace allocator<br/>[malloc.c]")]
  node_stl["STL allocator<br/>[StlAllocator.cpp]"]
  node_locks["Platform locks<br/>[TSPOS.hpp]"]
end

node_script(("Lua scripts"))
node_lua{{"Lua runtime"}}

node_script -->|"runs on"| node_lua
node_lua -->|"dispatches callbacks"| node_binding
node_binding -->|"reads and writes values"| node_lua
node_binding -->|"uses class metadata"| node_meta_api
node_meta -->|"implements metadata"| node_meta_api
node_meta -->|"converts Lua values"| node_lua
node_binding -->|"allocates and frees objects"| node_heap_api
node_heap -->|"allocates from mspace"| node_dlmalloc
node_heap -->|"falls back on exhaustion"| node_stl
node_heap -->|"uses optional locking"| node_locks

click node_binding "https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Base/LuaInterface.cpp"
click node_meta "https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Base/Meta.cpp"
click node_meta_api "https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Base/Meta.hpp"
click node_heap "https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Memory/Heap.cpp"
click node_heap_api "https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Memory/Heap.hpp"
click node_dlmalloc "https://github.com/that-sky-project/that-sky-engine/blob/main/libraries/dlmalloc-2.8.6/malloc.c"
click node_stl "https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Utils/StlAllocator.cpp"
click node_locks "https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Utils/TSPOS.hpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_binding toneBlue
class node_meta,node_meta_api toneAmber
class node_heap,node_heap_api,node_dlmalloc,node_stl,node_locks toneMint
class node_script,node_lua toneIndigo
```

## Components

### Lua interoperability

- [Lua bindings](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Base/LuaInterface.cpp): `src/Code/Base/LuaInterface.cpp`

### Runtime reflection

- [Metadata system](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Base/Meta.cpp): `src/Code/Base/Meta.cpp`
- [Metadata types](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Base/Meta.hpp): `src/Code/Base/Meta.hpp`

### Memory management

- [Tagged heap](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Memory/Heap.cpp): `src/Code/Memory/Heap.cpp`
- [Heap interface](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Memory/Heap.hpp): `src/Code/Memory/Heap.hpp`
- [Mspace allocator](https://github.com/that-sky-project/that-sky-engine/blob/main/libraries/dlmalloc-2.8.6/malloc.c): `libraries/dlmalloc-2.8.6/malloc.c`
- [STL allocator](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Utils/StlAllocator.cpp): `src/Code/Utils/StlAllocator.cpp`
- [Platform locks](https://github.com/that-sky-project/that-sky-engine/blob/main/src/Code/Utils/TSPOS.hpp): `src/Code/Utils/TSPOS.hpp`

### Other components

- **Lua scripts**
- **Lua runtime**

## Connections

- Lua scripts → Lua runtime: runs on
- Lua runtime → Lua bindings: dispatches callbacks
- Lua bindings → Lua runtime: reads and writes values
- Lua bindings → Metadata types: uses class metadata
- Metadata system → Metadata types: implements metadata
- Metadata system → Lua runtime: converts Lua values
- Lua bindings → Heap interface: allocates and frees objects
- Tagged heap → Mspace allocator: allocates from mspace
- Tagged heap → STL allocator: falls back on exhaustion
- Tagged heap → Platform locks: uses optional locking