If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/focus-creative-games/luban shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 8 active contributors
• MIT licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 85% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live focus-creative-games/luban repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/focus-creative-games/luban.

What it runs against: a local clone of focus-creative-games/luban — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in focus-creative-games/luban | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of focus-creative-games/luban. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/focus-creative-games/luban.git
#   cd luban
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of focus-creative-games/luban and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "focus-creative-games/luban(\\.git)?\\b" \\
  && ok "origin remote is focus-creative-games/luban" \\
  || miss "origin remote is not focus-creative-games/luban (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "README_EN.md" \\
  && ok "README_EN.md" \\
  || miss "missing critical file: README_EN.md"
test -f ".github/workflows/sync_gitee.yml" \\
  && ok ".github/workflows/sync_gitee.yml" \\
  || miss "missing critical file: .github/workflows/sync_gitee.yml"
test -f "LICENSE" \\
  && ok "LICENSE" \\
  || miss "missing critical file: LICENSE"
test -f ".gitignore" \\
  && ok ".gitignore" \\
  || miss "missing critical file: .gitignore"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/focus-creative-games/luban"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Luban is a game configuration management tool that converts multi-format source data (Excel, JSON, XML, YAML, Lua) into binary, JSON, or protobuf output across 12+ programming languages. It solves the complexity of managing game balancing, gameplay, and story data by providing a unified pipeline with built-in validation, inheritance-based type system, and zero-reflection code generation. Monolithic C# application with a plugin-based architecture. The core appears to be in src/ (not listed but typical), with docs/ containing extensive tutorials (adv/def_01.png through def_44.png suggest 44+ advanced definition guides). The tool ingests arbitrary formats through pluggable parsers and outputs via pluggable generators, supporting a clean separation between format-in, validation, and format-out stages.

Game developers (programmers and designers) building games in Unity, Unreal, Cocos2d-x, or Godot who need to manage large configuration datasets efficiently. Specifically useful for teams handling complex nested structures like skill trees, behavior trees, quest systems, and dungeon definitions across multiple platforms.

Actively developed with 1.5M+ lines of C# code and established community (QQ group 692890842, Discord, documented examples repo). MIT licensed with clear documentation at datable.cn. Appears production-ready with comprehensive feature set, though without visible GitHub workflow CI badges or recent commit timestamps in provided data, exact maintenance velocity is unclear.

Single language codebase (C# only, ~1.5M LOC) concentrates risk around .NET ecosystem. No visible test suite or CI pipeline (.github/workflows only shows gitee sync, not testing). Risk depends on active community uptake; reliance on unofficial examples repo (luban_examples) for onboarding suggests documentation may lag feature development.

No specific commit or PR data provided in the file listing. The repo maintains active documentation (docs/ structure complete) and community channels (Discord, QQ). The presence of .travis.yml suggests historical CI use; current GitHub Actions workflow at .github/workflows/sync_gitee.yml only syncs to Gitee mirror, not running tests.

git clone https://github.com/focus-creative-games/luban.git
cd luban
# Requires .NET SDK (version not specified; check README)
dotnet build
# See docs/ or https://www.datable.cn/docs/beginner/quickstart for example usage

Daily commands: Build with dotnet build. Run as CLI tool: luban --help or equivalent (exact invocation unclear without src/ inspection). See .github/workflows/sync_gitee.yml for build hints and https://www.datable.cn/docs/beginner/quickstart for workflow examples.

• README.md — Primary documentation in Chinese describing Luban's core features, architecture, and game configuration workflow—essential for understanding project scope and design philosophy.
• README_EN.md — English translation of core documentation covering supported formats, language generation, validation, and cross-platform capabilities.
• .github/workflows/sync_gitee.yml — CI/CD pipeline configuration showing build and deployment automation strategy for the main branch.
• LICENSE — MIT license defining legal constraints and permissions for contributors and users.
• .gitignore — Repository exclusion rules revealing what artifacts, build outputs, and dependencies are not version-controlled.

• Format Parser (Excel parser, JSON/YAML deserializers, XML DOM builder) — Reads Excel, JSON, YAML, XML, Lua files and converts to normalized internal AST; handles format-specific quirks
  • Failure mode: Unparseable files → build fails with line number; unsupported format extension → early error
• Schema Compiler (Type resolver, inheritance graph builder, generic type instantiation) — Compiles type definitions with inheritance into internal schema model; resolves type references and hierarchies
  • Failure mode: Circular inheritance → compile error; undefined type reference → build fails; incompatible override → schema validation error
• Data Validator (Pluggable validator interface, cross-reference resolver, constraint evaluator) — Runs pluggable validators (ref checks, range constraints, path existence) against data rows
  • Failure mode: Broken ref → validation error with row/column; range violation → validation error; missing resource path → validation error
• Code Generator (Template engine, language AST builders, protobuf/FlatBuffers schema emitter) — Generates language-specific classes, serialization code, and optional schemas (protobuf/FlatBuffers) for each target language
  • Failure mode: Unsupported type in target language → generation error; template syntax error → build fails; name collision → generated code conflict
• Data Exporter (Format-specific serializers, compression (optional), endianness handling) — Serializes validated configuration data to target format (binary, JSON, BSON, XML, Lua, YAML, msgpack)
  • Failure mode: Unsupported type in export format → export error; file write failure → IO error; corrupted output → checksum validation failure

• Source Files (Excel/JSON/YAML/XML/Lua) → Format Parser — Game designers edit configs in their preferred format; Luban reads and parses into normalized AST
• Format Parser → Schema Compiler — Parsed AST includes type definitions, field metadata, constraints; schema compiler resolves types and inheritance
• Schema Compiler → Data Validator — Compiled schema with type hierarchy passed to validators which check data rows against schema constraints
• Data Validator → Code Generator + Data Exporter — Validated data + schema passed to parallel generation pipeline: generates language code and exports serialized data
• Code Generator → Game Project (C#/Java/Go/Lua/TS code) — Generated classes imported into game project; enables type-safe config access at runtime

Add Support for a New Export Format

1. Review the existing format exporters in the codebase architecture to understand the plugin interface (docs/_config.yml)
2. Create a new exporter module following the established pipeline pattern for data serialization (README.md)
3. Register the new format in the core configuration pipeline (README_EN.md)

Add a New Language Code Generator

1. Examine how existing language generators (C#, Java, Go, etc.) are implemented in the codebase (README.md)
2. Implement the new language template following the generator abstraction pattern (README_EN.md)
3. Register the generator in the pipeline configuration and add it to the supported languages list (.github/workflows/sync_gitee.yml)

Extend Data Validation Rules

1. Review existing validation implementations (ref checks, range checks, path validation) in documentation (README.md)
2. Create a new validator module implementing the validation interface (README_EN.md)
3. Integrate the validator into the schema compilation and data verification pipeline (.editorconfig)

• Excel/CSV/JSON/YAML/XML/Lua support — Game designers use diverse tools; Luban unifies data entry across multiple formats to reduce friction in workflows
• Multi-language code generation (C#, Java, Go, C++, Lua, Python, TypeScript, Rust, PHP) — Modern game development spans multiple platforms and engines; single configuration source generates runtime code for each language/platform
• OOP type inheritance and complex nested structures — Game configurations are hierarchical (behavior trees, skill trees, dialogue systems); inheritance enables DRY configuration and polymorphic serialization
• Data validation (ref checks, range constraints, resource path verification) — Configuration errors cascade into production bugs; compile-time validation catches data issues before shipping
• Binary + JSON + Protocol Buffers + FlatBuffers export — Different runtime environments have different trade-offs: binary for size/speed, JSON for debuggability, protobuf for interop

• Support many input formats (Excel, JSON, YAML, XML, Lua) instead of forcing single canonical format

  • Why: Game teams have existing workflows and tool preferences; flexibility reduces onboarding friction
  • Consequence: Higher parser complexity and maintenance surface; requires format-specific validation and mapping logic

• Generate code + schemas for multiple languages instead of runtime-only approach

  • Why: Game engines need static types and IDE support; generating per-language classes enables type safety and tooling
  • Consequence: Large generated code footprint; generator must remain in sync as type system evolves

• Plugin-based architecture for extensibility rather than monolithic design

  • Why: Games have unique configuration needs; modular pipeline allows custom exporters, validators, and generators
  • Consequence: Steeper learning curve for second-order extensions; requires understanding pipeline abstractions

• Compile-time validation over runtime schema assertion

  • Why: Catches configuration errors early before they reach game clients; reduces debug cycles
  • Consequence: Schema validation rules must be upfront; complex rules require custom validator plugins

• Real-time collaborative editing (treats configs as batch-processed files, not live-sync documents)
• Runtime schema evolution without code regeneration (assumes schema changes require rebuild cycle)
• Encryption or DRM for configuration data (focuses on workflow, not security hardening)
• Automatic UI form generation for game designers (data entry format is external responsibility)

.NET SDK version not specified in file list—check README or .travis.yml for version constraints. Documentation heavily bilingual (Chinese + English) with primary docs at external datable.cn site, not repo; offline learning difficult. Plugin system extensibility is advertised but src/ structure not visible, making 'second development' barrier unclear. Excel handler for complex nested structures is a core differentiator but requires careful understanding of the format (see def_*.png guides).

• Object-Oriented Inheritance in Configuration Schema — Luban's type system supports OOP inheritance (mentioned explicitly in README), allowing game designers to define base skill/buff/quest types once and specialize them—critical for complex gameplay systems avoiding duplication
• Code Generation Pipeline (Zero-Reflection) — Luban generates code without calling reflection APIs, making output compatible with obfuscators and IL2CPP (Ahead-of-Time compilation in Unity/mobile games); understand this when debugging generated code or integrating with hybrid CLR
• Multi-Format Serialization (Binary, JSON, BSON, XML, Lua, YAML, Protobuf) — Game runtime may need different formats (binary for client efficiency, JSON for hot-reload during dev, protobuf for cross-platform networking); Luban single-source-of-truth approach prevents sync issues
• Reference Validation (Data Integrity Checking) — Luban validates ref links (e.g., skill ID → skill data), resource paths, and range constraints at export time, catching designer errors before they reach production—prevents runtime crashes from missing IDs
• Pluggable Parser & Generator Architecture — Core strength of Luban: custom parsers (e.g., proprietary CSV dialect) and generators (e.g., custom Lua dialect) via plugin system; second development requires understanding this extensibility pattern
• Localization Support (Internationalization in Game Config) — Built-in I18n support (mentioned in README) allows game text/UI strings to be managed in config system with language fallback—essential for global games but often overlooked in config tools
• Excel Format Enhancement (Nested Structures & Type Inheritance) — Luban extends Excel (CSV, XLS, XLSX, XLSM) to express complex nested types (sub-structures, struct lists, deep nesting) that designers understand visually—the 44 advanced guides (def_*.png) document this non-standard but powerful syntax

• focus-creative-games/luban_examples — Official example projects demonstrating Luban configuration workflows for real game scenarios; essential companion for learning by doing
• protocolbuffers/protobuf — Luban integrates Protocol Buffers as one of three optional message schemas (protobuf/flatbuffers/msgpack) for serialization
• google/flatbuffers — Alternative serialization backend integrated into Luban for schema + JSON generation, useful for zero-copy deserialization
• focus-creative-games/obfuz — Code obfuscation tool designed to work with Luban-generated C# code (zero-reflection guarantee), solving game security post-generation
• msgpack/msgpack-csharp — One of three serialization options in Luban for binary output format; CSharp implementation used for .NET targets

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive documentation for advanced OOP type inheritance patterns

The README highlights OOP type inheritance as a core feature for complex GamePlay data (behavior trees, skills, storylines, dungeons), but the docs/images/adv/ folder has 50 PNG files with no corresponding markdown documentation explaining these patterns. New contributors could create a structured guide mapping these visual examples to concrete implementation tutorials.

• [ ] Review docs/images/adv/def_01.png through def_50.png to understand the progression
• [ ] Create docs/advanced-oop-inheritance.md with sections for each pattern category
• [ ] Add code examples showing how to define inherited types in Excel/JSON/XML formats
• [ ] Document common use cases (behavior trees, skill systems, dungeon configs) with worked examples
• [ ] Link this guide from README.md and main documentation index

Create GitHub Actions workflow for multi-language code generation validation

The repo claims to support 10+ languages (C#, Java, Go, C++, Lua, Python, JavaScript, TypeScript, Rust, PHP, Erlang, Godot) but only has sync_gitee.yml workflow. Add a CI pipeline to validate that generated code for all supported languages compiles/passes syntax checks, catching regressions early.

• [ ] Create .github/workflows/validate-codegen.yml
• [ ] Add test matrix for C#/.NET, Java, Go, C++, Python, Node.js, Rust, PHP
• [ ] Configure each job to generate sample configs and validate syntax (compile or lint)
• [ ] Cache dependencies to keep CI fast
• [ ] Document expected setup in CONTRIBUTING.md

Add integration tests for supported file format readers (Excel, JSON, XML, YAML, Lua)

The README lists 5+ source data formats (csv, xls, xlsx, xlsm, json, xml, yaml, lua) as core features, but there's no visible test directory structure validating that each format parser correctly handles real-world configs. Create format-specific test suites with sample data files.

• [ ] Create tests/ directory structure: tests/fixtures/{excel,json,xml,yaml,lua}/
• [ ] Add sample config files for each format with identical data structures
• [ ] Create unit tests validating parser output matches expected AST/object representation
• [ ] Test edge cases: nested structures, multi-level inheritance, nullable fields, collections
• [ ] Document test conventions in docs/TESTING.md

• Add unit test suite for core parsing (CSV, JSON, XML handlers) in src/Luban/Parsers/*.cs—currently no visible /tests directory despite 1.5M LOC codebase
• Document .NET SDK version requirement and Python/Java/Go output examples in README.md matching the 12+ supported languages (currently mentions support but no concrete generated code samples)
• Create quick-reference cheat sheet for Excel 'enhanced format' syntax (nested structs, inheritance, complex lists) in docs/ to complement the 44 advanced guides—current docs/ only has images, no markdown tutorials

The Luban project appears to be a well-structured game configuration tool with MIT licensing and active maintenance. However, static analysis reveals moderate security gaps: (1) Dependency management files are not visible, preventing assessment of third-party vulnerabilities; (2) No formal vulnerability disclosure policy is documented; (3) CI/CD security hardening is minimal; (4) Code signing and branch protection mechanisms are not evident. These are primarily organizational/process issues rather than code-level vulnerabilities. The project would benefit from implementing a SECURITY.md policy, comprehensive dependency scanning, hardened CI/CD workflows with supply chain security controls, and enforcing commit signing and code review processes. The absence of executable code in the visible file structure (mostly documentation and configuration) limits assessment of injection vulnerabilities and data handling issues.

• Medium · Missing Dependency Management Visibility — Repository root / Package management files. No package.json, requirements.txt, pom.xml, or other dependency manifest files are visible in the provided file structure. This makes it impossible to assess whether the project uses vulnerable dependencies. For a project of this complexity, dependency vulnerabilities could pose significant security risks. Fix: Ensure all dependency files are present and regularly scanned using tools like OWASP Dependency-Check, npm audit, or Snyk. Implement automated dependency scanning in CI/CD pipelines.
• Medium · No Security Policy or Vulnerability Disclosure Process — .github/ directory. While a FUNDING.yml file exists for sponsorships, there is no visible SECURITY.md file or documented vulnerability disclosure process. This could delay critical security issue reporting and resolution. Fix: Create a SECURITY.md file in the repository root or .github/ directory documenting how security vulnerabilities should be reported (e.g., private disclosure, security advisory process).
• Low · Limited CI/CD Security Configuration — .github/workflows/sync_gitee.yml. Only a sync_gitee.yml workflow is visible. The workflow configuration lacks visible security hardening measures such as artifact signing, SBOM generation, or supply chain security controls. Fix: Implement security best practices in GitHub Actions workflows: use action pinning by commit hash, implement OIDC token verification, add artifact signing, generate SBOMs, and restrict workflow permissions with minimal necessary scopes.
• Low · No Code Signing Configuration Visible — Repository root. No visible code signing or GPG configuration (.gpg-id, signify files, etc.) in the repository. This could allow unsigned code commits that could be impersonated. Fix: Implement commit signing requirements using GPG or Sigstore. Configure branch protection rules to require signed commits and verified commits from trusted developers.
• Low · Incomplete Security Configuration — .github/ directory. No .github/security.yml, CODEOWNERS file, or branch protection configuration visible. This may indicate missing access control and code review enforcement mechanisms. Fix: Add CODEOWNERS file for code review requirements, create branch protection rules requiring PR reviews and status checks, and document security governance.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.