Ludots

SuperFastECSGameplayFramework - A high-performance, data-oriented gameplay framework built on Arch ECS.

中文文档 (Chinese)

Official entry: https://mightybubble.github.io/Ludots/ — documentation, Showcase gallery, test acceptance evidence, and the architecture diagram library, all aggregated in one place. New here? Start from the portal.

Ludots is a modern C# game framework designed for high-performance gameplay logic. It leverages ECS (Entity Component System) architecture, deterministic simulation, and a modular design to support complex game genres like MOBA, RTS, and Simulation games.

• High-Performance ECS: Built on Arch, optimized for speed and memory efficiency.
• Gameplay Ability System (GAS): A robust ability system inspired by UE GAS, supporting attributes, effects, and tags.
• Modular Architecture: Fully moddable with a Virtual File System (VFS) and hot-reloadable configurations.
• Advanced Navigation: Integrated NavMesh, MassNavigationFlow movement, and local avoidance (ORCA).
• Deterministic Simulation: Fixed-point math and deterministic scheduling for reliable networking and replay.
• Visual Editor: React-based visual editor for map editing and debugging.

The commands below are the canonical way to build and run. For the full newcomer guide (environment, showcase tour, acceptance evidence), see the Documentation Portal.

• .NET 9.0 SDK (only hard prerequisite)
• In-repo offline NuGet (external/nuget/): canonical paths work offline — no nuget.org hunt
• Node.js & npm (editor / Web only; Raylib CLI one-shot path does not need them)

The whole repo targets net9.0 (global.json pins SDK 9.0.x). Weak-network contract: Quick Start / zero-env setup.

Weak-network one-shot (recommended, Linux / macOS / Windows)

./scripts/dev-up.sh          # Linux/macOS: offline restore + build + launch ExampleMod

.\scripts\dev-up.ps1         # Windows

Other convenience scripts

Scripts are located in the scripts/ directory:

# Run the Visual Editor (Web + Bridge)
.\scripts\run-editor.cmd

# Run the Mod Launcher
.\scripts\run-mod-launcher.cmd

Manual Build (CLI)

# Run the Mass Navigation showcase through the launcher (canonical product entry)
.\scripts\run-mod-launcher.cmd cli launch mass_navigation --adapter raylib

Building the adapter app directly is for debugging only — it is not the product entry:

# Debug use only: build the Raylib adapter app
dotnet build .\src\Apps\Raylib\Ludots.App.Raylib\Ludots.App.Raylib.csproj -c Release

• src/Core/: The heart of the engine (ECS, GAS, Physics, Math).
• src/Apps/: Application entry points (Desktop/Raylib, Web).
• mods/: 30+ built-in and demo mods (outside src/ for UGC parity).
• src/Tools/: Developer tools (Launcher CLI, Editor.Bridge, AgentBridge, NavBake).
• src/Libraries/: Source-integrated third-party (Arch, DotRecast, Raylib-cs).
• docs/: Portal site source and in-repo deep materials (conventions, architecture, reference, ADR, audits, RFCs).

The single official entry is the Ludots Documentation Portal — documentation, Showcase gallery, test acceptance evidence, and the architecture diagram library are all published there.

• Writing source (markdown): gitbook/ — navigation in gitbook/SUMMARY.md, assembled into the portal by CI
• Contributing & Development — coding standards, feature development workflow, AI-assisted development rules, environment setup
• Showcase & acceptance registry: showcase.registry.json (repo root)
• In-repo deep materials — portal site source, ADR, audits, RFCs, and long-form design docs

This project is licensed under the AGPL-3.0 License. This means if you use this code in a project that is distributed (including over a network), you must also open source your project under the same AGPL license.

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

We gratefully acknowledge the following open-source projects that make Ludots possible.

Disclaimer: All trademarks and registered trademarks are the property of their respective owners.