supervisor-simulator/specs/numerical_design_system.md

Numerical Design & Balancing System (NDBS) - Implementation Guide

Version: 2.0 Target Stack: Python 3.14 (FastAPI, uv), Vue.js (Vite), C# (Godot .NET) Role: AI Developer Guide

1. System Overview

The NDBS is a local web application enabling game designers to:

1. Edit Game Data: Modify JSON files in resources/definitions/ (Traits, Archetypes, Items) via a GUI.
2. Script Logic: Write C# code for RuleIds (special game logic) in a browser-based IDE. The system auto-generates the corresponding .cs files in scripts/Rules/Generated/.

This guide is structured as a sequence of tasks for an AI agent to implement the system incrementally.

---

2. Architecture

The system is designed as a Unified Web Service. A single Python process handles both the API logic and serving the frontend interface.

1. NDBS Service (Python/FastAPI):
   • API Layer: Handles data reading/writing and script generation (/api/*).
   • Static Layer: Serves the compiled Vue.js application (index.html, js/, css/) from the client/dist directory.
2. NDBS Web Client (Vue.js):
   • Developed as a standard SPA.
   • Built into static files (npm run build) which are consumed by the Python service.

Runtime Flow: User runs python main.py -> Browser opens http://localhost:8000 -> Frontend loads -> Frontend calls /api/... -> Python modifies files.

graph TD
    User[Designer] -->|Browser| Service[NDBS Python Service]
    Service -->|Serve Static| Frontend[Vue.js UI]
    Service -->|API| Logic[Business Logic]
    Logic -->|Read/Write| JSON[JSON/TRES Definitions]
    Logic -->|Generate| CSharp[C# Rule Scripts]

---

3. Implementation Phases

Phase 1: Python Backend Foundation

Goal: Establish a FastAPI server that can read/write the game's JSON files.

Step 1.1: Environment Setup

• Instruction: Create tools/ndbs/server/. Initialize a Python environment using uv.
  • Run uv init --python 3.14 to set up the project.
  • Run uv add fastapi uvicorn pydantic to install dependencies.
• Code Requirement: Create tools/ndbs/server/main.py.
• Key Functionality:
  • Enable CORS (allow all origins for dev).
  • Define a constant PROJECT_ROOT pointing to ../../../../.

Step 1.2: File System API

• Instruction: Implement endpoints to list and read definitions.
• Endpoints:
  • GET /api/files/definitions: Scans resources/definitions/ and returns a list of .json AND .tres files.
  • GET /api/files/content: Takes a filename query param.
    • If .json: Returns parsed JSON.
    • If .tres: Parses the [resource] section key-value pairs into a JSON object. Handles arrays (e.g., Tags = [ "a", "b" ]) and strings.
  • POST /api/files/content: Takes filename and content (JSON body).
    • If .json: Writes standard JSON.
    • If .tres: Reads the original file, replaces the values in the [resource] section with new values from the JSON, and saves preserving the header/metadata.

Step 1.3: Schema Inference (Dynamic Models)

• Instruction: Since we don't have hardcoded Pydantic models for every file, create a utility that reads a file ( JSON or TRES) and generates a generic "Schema" description (listing keys and value types) to help the frontend build forms dynamically.

Step 1.4: Static Asset Serving (SPA Support)

• Instruction: Configure FastAPI to serve the frontend.
  • Mount the client/dist directory to / as static files.
  • Critical: Implement a "Catch-All" route (after API routes) that returns client/dist/index.html. This ensures that Vue Router paths (e.g., http://localhost:8000/editor/archetypes) work when refreshed.

---

Phase 2: Vue.js Frontend Foundation

Goal: A clean UI to browse files and edit JSON data.

Step 2.1: Project Scaffolding

• Instruction: Create tools/ndbs/client using Vite + Vue 3 (TypeScript). Install axios, pinia, and naive-ui.

Step 2.2: File Explorer & Layout

• Instruction: Create a standard "Sidebar + Main Content" layout.
  • Sidebar: Fetches the list of files from GET /api/files/definitions and displays them as a menu.
  • Main Content: A RouterView to show the editor.

Step 2.3: Generic JSON Editor

• Instruction: Create a component JsonEditor.vue.
  • Fetch content using GET /api/files/content.
  • Display the raw JSON in a textarea (Monaco Editor preferred later).
  • Add a "Save" button that calls POST /api/files/content.

Step 2.4: Build Integration

• Instruction: Configure vite.config.ts to output to ../server/client_dist (or just dist inside client, and server reads from there).
  • Ensure the "Build" command produces the artifacts expected by Step 1.4.

---

Phase 3: C# Rule Engine Integration (Godot Side)

Goal: Prepare the game code to dynamically load the scripts we will generate later.

Step 3.1: Define the Interface

• Instruction: Create scripts/Core/Interfaces/IGameRule.cs.

  namespace Core.Interfaces;
  using Models;
  public interface IGameRule {
      string Id { get; }
      // Example hooks - adjust based on GameSystems.cs analysis
      void OnEvent(GameSession session, object gameEvent);
      void ModifyStats(UnitModel unit, StatRequest request);
  }
  

Step 3.2: Rule Manager (The Loader)

• Instruction: Create scripts/Core/Systems/RuleManager.cs.
  • Use Reflection to find all classes implementing IGameRule.
  • Store them in a Dictionary<string, IGameRule>.
  • Provide a method ExecuteRule(string ruleId, ...) that looks up the rule and calls its methods.

Step 3.3: Hook into Game Systems

• Instruction: Modify scripts/Core/GameSystems.cs (specifically SynergySystem or TaskSystem).
  • Find where RuleIds are iterated.
  • Inject a call to RuleManager.Instance.ExecuteRule(ruleId, ...) inside those loops.

---

Phase 4: Scriptable Rule Editor (Full Stack)

Goal: Allow creating new C# rules from the web UI.

Step 4.1: Backend - Template Generator

• Instruction: Add endpoint POST /api/rules/create.
  • Params: rule_id (e.g., "grinder_stress_effect").
  • Action:
    1. Validate naming (alphanumeric).
    2. Load a C# template string (Class name = Rule_{CamelCaseId}).
    3. Write file to scripts/Rules/Generated/Rule_{CamelCaseId}.cs.
    4. Return success.

Step 4.2: Frontend - C# Editor

• Instruction: Add a "Rules" section to the sidebar.
  • List .cs files in scripts/Rules/Generated/ (add backend endpoint for this).
  • Integrate Monaco Editor (Vue wrapper) for syntax highlighting.
  • Save button writes the C# content back to disk.

Step 4.3: Compilation Trigger (Optional but Recommended)

• Instruction: Add a "Verify" button.
  • Backend endpoint POST /api/build.
  • Runs dotnet build shell command.
  • Returns stdout/stderr to the frontend console.

---

4. Technical Constraints & Conventions

4.1 File Paths

• Server Root: tools/ndbs/server
• Game Root: ../../ (Relative to server)

4.2 Coding Style

• Python: Type hints (Python 3.14), Pydantic models for request/response bodies. Use uv for dependency management.
• Vue: Composition API (<script setup lang="ts">), Scoped CSS.
• C#: Namespace Rules.Generated for all generated scripts.

4.3 Safety

• No Overwrite: When creating a new rule, fail if the file already exists.
• Backup: (Bonus) Before saving a JSON file, copy the old version to tools/ndbs/backups/.