wjsjwr ac1cef31ac Update spec for NDBS

2026-01-17 15:25:16 +08:00

6.7 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:

Edit Game Data: Modify JSON files in resources/definitions/ (Traits, Archetypes, Items) via a GUI.
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 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.

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/.

6.7 KiB Raw Blame History