wjsjwr/supervisor-simulator
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
5cf70ccf4b
supervisor-simulator/specs/numerical_design_system.md
wjsjwr 5cf70ccf4b Fix grid system
2026-01-17 14:27:36 +08:00

6.8 KiB
Raw Blame History

Numerical Design & Balancing System (NDBS) - Implementation Guide

Version: 2.0 (AI-Actionable) Target Stack: Python (FastAPI), 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. Directory Structure Plan

The tool will reside in a new tools/ndbs/ directory, keeping it separate from the game assets but with access to them.

D:\code\super-mentor\
├── resources\definitions\      <-- Target Data Source
├── scripts\Rules\Generated\    <-- Target Script Output
├── tools\
│   └── ndbs\
│       ├── server\             <-- Python Backend
│       │   ├── main.py
│       │   └── ...
│       └── client\             <-- Vue Frontend
│           ├── src\
│           └── ...

3. Implementation Phases (AI Prompts)

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. Install fastapi, uvicorn, pydantic.
  • 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 files.
    • GET /api/files/content: Takes a filename query param; returns the parsed JSON content.
    • POST /api/files/content: Takes filename and content (JSON body); writes it back to resources/definitions/{filename} with 2-space indentation.

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 JSON file and generates a generic "Schema" description (listing keys and value types) to help the frontend build forms dynamically.

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 (state management), and naive-ui (or element-plus) for UI components.

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, start simple).
    • Add a "Save" button that calls POST /api/files/content.
    • Enhancement: Use a library like jsoneditor or v-jsoneditor to provide a tree view/form view.

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
  • Client Root: tools/ndbs/client
  • Game Root: ../../ (Relative to server)

4.2 Coding Style

  • Python: Type hints (Python 3.10+), Pydantic models for request/response bodies.
  • 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/.

5. "Get Started" Prompt for AI

To begin implementing this spec, paste the following prompt:

"I need to initialize the NDBS server as defined in Phase 1 of specs/numerical_design_system.md. Please create the directory tools/ndbs/server, set up a basic FastAPI main.py application, and implement the file listing endpoint GET /api/files/definitions that reads from resources/definitions/. Use uvicorn to run it on port 8000. Ensure CORS is enabled."