Xiangke (相剋)

A Three Kingdoms turn-based command battle game built with Godot Engine 4.7 and Rust GDExtension.

Important

This project is under active development. APIs, game mechanics, and project structure may change without notice.

📖 Overview

Xiangke (相剋) is a turn-based command battle game set in the era of the Three Kingdoms. Players command legendary generals, each with unique abilities based on Yin-Yang and the Five Elements (陰陽五行) principles.

The game logic core is implemented in Rust for performance and safety, bridged to Godot via gdext. The primary export target is Web (HTML5/WebAssembly).

🏗️ Architecture

graph TB
    subgraph GodotEngine["Godot Engine"]
        subgraph GDScriptLayer["GDScript Layer"]
            scenes["scenes/"]
            scripts["scripts/"]
            autoloads["autoloads/"]
            systems["systems/"]
        end

        GDScriptLayer -->|"gdext FFI"| RustGDE

        subgraph RustGDE["Rust GDExtension (extensions/)"]
            core["core/<br/>Game Logic"]
            battle["battle/<br/>Combat Engine"]
            bridge["godot_bridge/<br/>Godot Bindings"]
        end

        bridge --> core
        bridge --> battle
    end

Loading

📁 Project Structure

xiangke/
├── addons/gdext/              # GDExtension shared libraries
├── audio/
│   ├── bgm/                   # Background music (3 tracks)
│   └── sfx/                   # Sound effects (7 clips)
├── autoloads/                 # Autoloaded singletons
│   ├── audio_manager.gd       # BGM/SFX playback & web autoplay
│   ├── data_registry.gd       # Central game data registry
│   ├── game_manager.gd        # Game state management
│   ├── save_manager.gd        # Local persistence (ConfigFile)
│   └── ui_focus_manager.gd    # UI focus & navigation
├── extensions/                # Rust GDExtension workspace
│   ├── core/                  # Core game logic (types, type chart)
│   ├── battle/                # Battle engine (flow, state, participants)
│   ├── godot_bridge/          # Godot ↔ Rust bindings (cdylib)
│   └── Cargo.toml             # Workspace root
├── resources/
│   ├── characters/            # 13 character .tres files
│   ├── moves/                 # 8 move .tres files
│   └── status_effects/        # 5 status effect .tres files
├── scenes/                    # 5 game scenes
├── scripts/
│   ├── character_data.gd      # Character data resource
│   ├── move_data.gd           # Move data resource
│   ├── status_effect_data.gd  # Status effect definitions
│   ├── type_chart.gd          # Elemental effectiveness chart
│   ├── type_enums.gd          # Shared enums (Elements, etc.)
│   └── foundation/            # Scene logic & UI scripts
├── systems/
│   ├── battle/                # Battle flow, state, participant
│   └── data/                  # Data loading & validation
├── tests/                     # GDScript unit tests
├── justfile                   # Build & dev commands
└── project.godot              # Godot project configuration

🚀 Getting Started

Prerequisites

• Godot Engine 4.7
• Rust toolchain (stable)
• just command runner
• For Web builds only: Rust nightly toolchain + Emscripten SDK

Installation

git clone https://github.com/makinosp/xiangke.git
cd xiangke
just build-rust       # Build Rust GDExtension (native)

Then open project.godot in Godot Engine.

Running

just run              # Build Rust + launch Godot

Or press F5 in the Godot editor.

🔨 Development Commands

Command	Description
just build-rust	Build Rust GDExtension for native (debug)
just build-rust-wasm	Build Rust GDExtension for Web (WASM)
just build-rust-wasm-release	Build WASM in release mode with size opt
just check-rust-wasm	Quick-check WASM compilation
just test-rust	Run Rust unit tests (200 tests)
just check-rust	Run cargo check on Rust workspace
just run	Build Rust + launch Godot
just inspect	Headless Godot validation (no errors)

🎯 How to Play

1. Select your general from the roster
2. Choose your moves strategically based on enemy elemental weaknesses
3. Manage your resources (HP, Spirit, etc.) to unleash powerful techniques
4. Defeat all enemy forces to claim victory!

🧠 Game Mechanics

Elemental System (五行 + 陰陽)

• Wood (木) → Earth (土) → Water (水) → Fire (火) → Metal (金) → Wood (木) (cycle)
• Yin (陰) and Yang (陽) are special elements that interact uniquely
• Each element has strengths and weaknesses against others

🧪 Testing

The project includes 235 tests across two stacks:

• Rust (200 tests): Core logic and battle engine

  just test-rust

• GDScript (35 tests): Autoloads, type system, UI focus manager Run via Godot's test runner (tests/test_runner.tscn).

📜 License

This project is licensed under the GNU Affero General Public License v3.0 — see the LICENSE file for details.