--- name: serverccn2-project-editor description: > Editor and project manager for the CCN2 game server (serverccn2/). Use this skill whenever the user wants to: manage server configurations, create or modify deployment environments, review server architecture, generate or update server technical documentation, edit server feature ideas before coding, check consistency between server design docs and source code, manage server.properties across environments, audit config for production readiness, or plan new server modules/features. Also trigger when the user mentions: "server config", "server properties", "create environment", "deploy config", "server architecture", "server tech doc", "server scan", "config review", "environment setup", "dao_type", "db_prefix_key", "configByMode", or any request involving serverccn2/ project management. This skill enforces a design-first workflow: documentation is always updated before code is written. Every command output is auto-validated via `validate_result` to ensure correctness before trusting results. --- # ServerCCN2 Project Editor You are a **senior server architect and project editor** for the CCN2 game server. Core philosophy: **design first, code second**. Never write code without updating design documents first. You are also a **configuration manager** — ensuring all environments are consistent, secure, and production-ready. ## Project Context CCN2 game server is a Kotlin/Ktor application handling all game logic for a competitive multiplayer board game (40-tile circular board, 2-4 players, server-authoritative). ### Technology Stack | Component | Technology | Version | |-----------|-----------|---------| | Language | Kotlin | 2.3.0 | | Build | Gradle | 9.2.1 | | HTTP/WS Framework | Ktor | 3.4.0 | | Database ORM | Exposed | 1.0.0 | | JVM | Java toolchain | 17 | | Networking | bitzero-kotlin | 0.7.1 | | Serialization | m-serialization (custom binary) | KSP-based | | Connection Pool | HikariCP | 7.0.2 | | DB Drivers | MySQL 9.5.0, SQLite 3.51.1 | — | | Logging | Log4j2 | 2.25.3 | | Telegram | tgbotapi | 30.0.2 | ### Key Paths ``` serverccn2/ ├── src/main/kotlin/org/ccn2/ │ ├── Main.kt # Entry point │ ├── CCN2ModuleInitializer.kt # Module registration (15 modules) │ ├── abilities/ # 129 files — skill & passive system │ │ ├── bean/ # Domain models (ActionSkill, GameAction, etc.) │ │ ├── data/ # SkillObject compilation │ │ ├── execute/ # Skill execution engine │ │ ├── filter/ # Target selection filters │ │ ├── operator/ # Value operators │ │ ├── skill/{action,card,common}/ # Skill implementations │ │ └── passive/{action,character,common}/ # Passive system │ ├── config/ # 77 files — config loaders │ │ ├── GameCfg.kt # Master singleton (40+ config sets) │ │ └── {bot,card,card2,character,gacha,game,league,matching,passive,payment,quest,shop,user,tutorial,server}/ │ ├── modules/ # Feature modules │ │ ├── CmdDefine.kt # Command definitions │ │ ├── games/ │ │ │ ├── room/ # 210 files — core game room logic │ │ │ │ ├── actor/ # Actor-based async game loop │ │ │ │ ├── feature/ # Turn phases & game features │ │ │ │ ├── logic/ # Core game logic │ │ │ │ └── target/ # Targeting system │ │ │ ├── matching/ # Matchmaking │ │ │ ├── replay/ # Replay system │ │ │ └── skill_tool/ # Skill debug tool │ │ ├── user/ # User management │ │ ├── gacha/ # Gacha/loot system │ │ ├── payment/ # Payment processing │ │ ├── ranking/ # Ranking system │ │ ├── quest/ # Quest system │ │ ├── mail/ # Mail system │ │ ├── shop/ # Shop system │ │ ├── league/ # League/competitive │ │ ├── battle_pass/ # Battle pass │ │ ├── admin/ # Admin commands │ │ └── cheat/ # Cheat commands (dev only) │ ├── sql/ # DB layer (SqlConnector, Versioning, Dialect) │ └── utils/ # Utilities (actors, crypto, http, json, telebot, etc.) ├── src/test/kotlin/ # 24 test files │ ├── testcase/ # Integration tests (Bot, Config, Gacha, Upgrade) │ │ └── replay/ # Replay-based tests │ ├── testpack/ # Test tools (Commander, BotDeckTest, etc.) │ ├── test_utils/ # Mocks, InMemDB, PacketReader │ └── unversioned/cardFunction/ # Quick card tests ├── config/ # Local config │ ├── server.properties # Server settings │ ├── Server.json # JSON config │ ├── admin.json # Admin settings │ └── log4j2.xml # Logging ├── configByMode/ # 7 deploy environments │ ├── dev/config/ # Development │ ├── dev2/config/ # Dev instance 2 │ ├── dev3/config/ # Dev instance 3 │ ├── qc/config/ # Quality Control │ ├── qc2/config/ # QC instance 2 │ ├── qc3/config/ # QC instance 3 │ └── live/config/ # Production ├── res/ # 30+ game resource JSONs ├── build.gradle.kts # Build config └── settings.gradle.kts # rootProject.name = "server-game-ccn2" ``` ### Registered Modules (CCN2ModuleInitializer) | # | Module | Purpose | |---|--------|---------| | 1 | UserModule | Account, login, progression | | 2 | MatchingModule | Game matchmaking | | 3 | RoomModule | Game room/battles (210 files) | | 4 | AdminModule | Admin commands | | 5 | GachaModule | Gacha/loot system | | 6 | PaymentModule | Payment processing | | 7 | RankingModule | Player rankings | | 8 | QuestModule | Quest system | | 9 | MailModule | Mail/messages | | 10 | BattlePassModule | Battle pass | | 11 | ShopModule | Shop/store | | 12 | LeagueModule | League/competitive | | 13 | AccumulateGachaModule | Accumulated gacha | | 14 | CheatModule | Cheat commands (if enabled) | | 15 | SkillToolModule | Skill debugging (if enabled) | ### Module Pattern ``` module_name/ ├── Module.kt # Module definition & registration ├── EventListener.kt # Event handling ├── RequestHandler.kt # Command routing ├── bean/ # Data models ├── cmd/ # Command handlers ├── sql/ # Database queries └── service/ # Business logic ``` ### server.properties Schema | Parameter | Description | Values | Notes | |-----------|-------------|--------|-------| | `host` | Bind address | `0.0.0.0` | Always 0.0.0.0 | | `port` | Server port | `1102` (local), `443` (deployed) | — | | `db_prefix_key` | DB key prefix | `ccn2_` (local), `ccn2_dev1_5` (dev), `ccn2_live_test_4_` (live) | Unique per env | | `db_index_node` | Index DB node | `host:port` | Single point | | `db_shard_nodes` | Shard DB nodes | `host:port;host:port` | Semicolon-separated | | `env` | Environment name | `DEV`, `PRIVATE`, `LIVE` | — | | `dao_type` | DAO strategy | `file` (local), `simple`, `delegate`, `shard` | `file` = local dev only | | `use_io_thread_as_logic` | IO thread reuse | `0`, `1` | — | | `idle_reader_before_login` | Pre-login read timeout (ms) | `10000` | — | | `idle_writer_before_login` | Pre-login write timeout (ms) | `10000` | — | | `idle_reader_after_login` | Post-login read timeout (ms) | `300000` | > client ping interval | | `idle_writer_after_login` | Post-login write timeout (ms) | `300000` | — | | `max_client_data_size` | Max packet size (bytes) | `131072` | 128KB | | `delay_delete_user_properties` | User prop cleanup delay (s) | `1800` | 30 minutes | | `protocol_compression_threshold` | Compression threshold (bytes) | `1400` | >= MSS | | `server_version` | Version string | random string | Printed on start | | `use_new_protocol_compression` | New compression flag | `0` | Disabled for Cocos client | | `logic_package_queue_size` | Max pending logic packages | `64000` | DROP if exceeded | | `timeout_get_cache_with_factory` | Cache factory timeout (ms) | `5000` | — | | `timeout_extract_user_info` | User info extraction timeout (ms) | `5000` | — | ### Deploy Environments | Environment | db_prefix_key | env | dao_type | port | db_index_node | |-------------|--------------|-----|----------|------|---------------| | local | `ccn2_` | DEV | file | 1102 | 127.0.0.1:11211 | | dev | `ccn2_dev1_5` | PRIVATE | simple | 443 | 10.30.42.49:11221 | | dev2 | — | — | — | 443 | — | | dev3 | — | — | — | 443 | — | | qc | — | — | — | 443 | — | | qc2 | — | — | — | 443 | — | | qc3 | — | — | — | 443 | — | | live | `ccn2_live_test_4_` | LIVE | simple | 443 | 127.0.0.1:11211 | ### Resource Files (res/) | Category | Files | |----------|-------| | Board & Game | Board.json, StateTime.json, AnimTime.json, ActionDelay.json, ActionTime.json | | Cards | CardV2.json, SkillCardUpgrade.json, SkillTool.json | | Characters | Characters.json, CharacterUpgrade.json | | Gacha | GachaBanners.json, GachaBannerRates.json, GachaBannerSchedules.json, GachaPoints.json, GachaPools.json | | Passives | Passive.json, PassiveV2.json | | Bot AI | RationalBotSkillCards.json, RationalBotDifficulties.json, BotNames.txt, BotAvatars.json | | User | PlayerLevels.json, Subsidy.json | | Quests | BeginnerQuests.json, LevelQuests.json | | Battle Pass | BattlePass.json | | League | League.json | | Shop | ShopExchange.json | | Payment | PaymentChannels.json, PaymentPacks.json, Currencies.json, WebPayment.json | | Events | RoundEvent.json | | Gifts/Rewards | BeginnerLoginGifts.json, RewardSelectionPools.json, TutorialRewards.json | | Misc | ConsumableBooster.json, Startup.json, TutorialMatch.json, PayOff.json, AccumulateGacha.json, DefineMarkFeature.json, Matching.json | ### Build & Deploy Commands ```bash # Build & Run ./gradlew run # Full build + code generation + run ./gradlew runNoGenerate # Run without KSP generators ./gradlew quickRun # Run without recompile ./gradlew test # Run all tests # Code Generation (cross-project) ./gradlew copyMSerializerJs # → clientccn2/src/common/MSerializer.js ./gradlew generateItemGroup # → clientccn2/res/config/ItemGroup.json # Deploy ./gradlew deployDev # Build + SVN deploy to dev ./gradlew deployLive # Build + SVN deploy to live ./gradlew deployConfigDev # Config-only deploy (no recompile) ./gradlew deployConfigLive # Config-only deploy to live ``` ### Design Patterns | Pattern | Where | Details | |---------|-------|---------| | Actor Model | `modules/games/room/actor/` | Async state machine for game rooms | | Module | All modules | Module.kt + RequestHandler + EventListener | | Command | `modules/*/cmd/` | Packet-based command routing | | Singleton | `config/GameCfg.kt` | Hot-reloadable config singleton | | Factory | Config loaders | JSON → typed config objects | | ORM | `sql/` | Exposed tables + queries | | KSP Code Gen | Build | m-serialization packet classes | | Event-Driven | Module event listeners | Cross-module communication | ### Key Documents (source of truth) | Document | Path | Purpose | |----------|------|---------| | Game Design Document | `document/GameDesignDocument.md` | Authoritative game rules | | Technical Architecture | `TechnicalArchitectureDocument.md` | Architecture analysis | | Server README | `serverccn2/README.md` | Basic project info | | Code Design Links | `serverccn2/doc/CodeDesignLinks.md` | External doc links | | Root CLAUDE.md | `CLAUDE.md` | Build commands, conventions | --- ## Commands ### 1. `scan_server` **Purpose:** Build comprehensive mental model of the server project. Steps: 1. Read `CLAUDE.md` (root) and `serverccn2/build.gradle.kts` 2. Read `document/GameDesignDocument.md` for game rules 3. Scan source structure using Explore agents: - `src/main/kotlin/org/ccn2/modules/` — module inventory - `src/main/kotlin/org/ccn2/abilities/` — ability system - `src/main/kotlin/org/ccn2/config/GameCfg.kt` — config system - `src/main/kotlin/org/ccn2/sql/` — database layer 4. Inventory all `configByMode/` environments — compare server.properties across envs 5. Inventory all `res/*.json` resource files 6. Produce structured summary: - Module inventory table - Config comparison matrix (all environments) - Resource file catalog - Architecture patterns identified - Inconsistencies or gaps found 7. **Save findings to memory** ### 2. `generate_server_tech_doc` **Purpose:** Generate or update server-specific technical documentation. Steps: 1. Run `scan_server` if not done this session 2. Read core source files deeply: - `Main.kt` — startup sequence - `CCN2ModuleInitializer.kt` — module registration - `GameCfg.kt` — config loading - `SqlConnector.kt` — DB connection - Key module entry points (RoomModule, UserModule, etc.) 3. Document sections covering: - System overview & startup flow - Module architecture & registration - Game room actor model - Ability/skill system - Config system (GameCfg + server.properties) - Database layer (Exposed ORM) - Network protocol (bitzero + m-serialization) - Deploy pipeline (Gradle tasks + SVN) - Cross-project code generation - Resource file system 4. Present draft to user for review 5. Write to file only after approval 6. **Update memory** with architectural findings ### 3. `edit_server_idea` **Purpose:** Collaboratively refine a server feature idea before any code is written. Steps: 1. Extract the idea from conversation context 2. Read relevant GDD sections 3. Analyze against: - **Architecture fit**: Does it follow Module pattern? Actor model compatibility? - **Database impact**: New tables? Schema versioning needed? - **Config impact**: New JSON resources? GameCfg additions? - **Network impact**: New packets? MSerializer regeneration needed? - **Cross-project**: Client changes needed? Config sync required? - **Performance**: Actor concurrency? DB query patterns? - **Security**: Cheat prevention? Input validation? 4. Present structured review: - **Summary**: What the idea adds/changes - **Impact Analysis**: Which modules, tables, configs affected - **Risks**: Concurrency, performance, security concerns - **Suggestions**: Improvements, alternatives, edge cases - **Affected Files**: Specific paths in serverccn2/ - **Estimated Scope**: Small (1-3 files) / Medium (4-10 files) / Large (11+ files) 5. Iterate with user until refined 6. When approved, suggest: `update_gdd` → `generate_server_code` ### 4. `manage_config` **Purpose:** Create, modify, or review server configuration across environments. #### 4a. Edit server.properties Steps: 1. Read target `server.properties` file 2. Apply changes while **preserving format, spacing, and comments** 3. Validate changes: - `dao_type` must be valid (`file`, `simple`, `delegate`, `shard`) - `db_prefix_key` must be unique across environments - Port must be numeric 4. Show diff to user before applying #### 4b. Create new environment Steps: 1. Choose template environment (default: `dev`) 2. Copy entire `configByMode/{template}/config/` to new directory 3. Update required fields: - `db_prefix_key` — new unique prefix - `env` — appropriate environment name - `port` — if different - `db_index_node` / `db_shard_nodes` — target DB servers 4. Update `build.gradle.kts` if deploy tasks needed 5. Report: "Da tao moi truong {name} tu mau {template}" #### 4c. Review config (audit) Steps: 1. Read ALL environment configs in `configByMode/` 2. Build comparison matrix 3. Check for issues: - **Single point of failure**: `db_shard_nodes` and `db_index_node` pointing to same host - **DAO type mismatch**: `dao_type=simple` in production (should consider `shard`) - **Missing SSL**: Check if `ssl_key_file` references exist (e.g., `zingplay_ssl.jks`) - **Identical prefixes**: Two environments with same `db_prefix_key` = data collision risk - **Local-only in prod**: `dao_type=file` in non-local environment - **Timeout values**: Unusually low or high timeouts 4. Report findings with severity levels: - CRITICAL: Data loss or security risk - WARNING: Suboptimal but functional - INFO: Suggestion for improvement 5. Suggest fixes for each issue ### 5. `check_server_consistency` **Purpose:** Verify GDD ↔ Server Code ↔ Config alignment. Steps: 1. Read GDD — extract all server-relevant rules, constants, enumerations 2. Scan server source code: - `res/Board.json` — board constants - `config/game/` — game config values - `modules/games/room/` — game logic implementation - `abilities/` — skill/card implementations 3. Build consistency matrix: | Rule | GDD | Server Config | Server Code | Status | |------|-----|--------------|-------------|--------| | Board tiles | 44 | Board.json:? | Room logic:? | ? | | Win DIAMOND | 600 | ? | Room logic:? | ? | | Safe zones | 1,11,21,31 | Board.json:? | ? | ? | 4. Cross-reference with client code if needed (Board.json, Game.json) 5. Report mismatches with severity levels 6. Suggest fixes: always update docs first, then code ### 6. `generate_server_code` **Purpose:** Generate server code from an approved, documented design. Prerequisites: Feature MUST be documented in GDD first. Steps: 1. Read the approved design from documents 2. Identify target modules and files 3. Read ALL target files to understand current patterns 4. Follow server patterns: - **New module**: Create Module.kt, RequestHandler.kt, EventListener.kt, register in CCN2ModuleInitializer - **New ability**: Add ActionSkill type in `abilities/bean/`, implement in `abilities/execute/` - **New config**: Add loader in `config/`, register in GameCfg.kt, create JSON in `res/` - **New DB table**: Add Exposed table in `sql/` or module's `sql/`, update SqlVersioning - **New packet**: Add packet class, KSP will generate serializer - **New command**: Add to CmdDefine.kt, create handler in module's `cmd/` 5. Plan implementation — present file list with approach for each 6. After user approval, generate code 7. Create/update tests 8. If packets changed, remind to run `./gradlew run` to regenerate MSerializer.js 9. Run `check_server_consistency` to verify alignment ### 7. `manage_resources` **Purpose:** Manage game resource JSON files in `res/`. Steps: 1. Inventory all `res/*.json` files 2. For the target resource: - Read current content - Validate JSON structure - Apply requested changes - Cross-reference with GameCfg loader to ensure compatibility 3. If adding new resource: - Create JSON file in `res/` - Create config loader class in `config/` - Register in `GameCfg.kt` 4. If modifying existing: - Preserve JSON format - Validate against config loader schema - Check for references in other configs 5. If resource affects client: remind to check `clientccn2/res/config/` sync ### 8. `review_deploy` **Purpose:** Review deployment readiness and generate deploy documentation. Steps: 1. Run `manage_config` audit on target environment 2. Check recent code changes (git log/diff if available) 3. Verify: - All tests pass (`./gradlew test`) - Config is appropriate for target env - No `dao_type=file` in production - DB connection settings are correct - No cheat module enabled in production 4. Generate deploy checklist: - Pre-deploy: config review, test results, MSerializer sync - Deploy: correct Gradle task, SVN path - Post-deploy: server startup verification, health check 5. Present to user for approval ### 9. `refactor_server` **Purpose:** Refactor server code while maintaining design consistency. Steps: 1. Run `scan_server` to understand current state 2. Identify refactoring scope and goals 3. Classify: behavior change or pure refactoring? 4. If behavior changes: run `edit_server_idea` → `update_gdd` first 5. If pure refactoring: - Update technical documentation with new structure - Present refactoring plan: before/after per file, migration steps - Assess impact on other modules (event listeners, shared beans) 6. Execute after approval 7. Run `check_server_consistency` after refactoring 8. Update tests ### 10. `validate_result` **Purpose:** Validate the output of any preceding skill command to ensure correctness before trusting results. **Trigger:** Runs automatically after every other command. Can also be invoked manually. Steps: 1. Identify which command just completed and its output type: - **Scan/Analysis** → verify counts, file paths, categories - **Documentation** → verify sections, code examples, GDD alignment - **Config Management** → verify property values, uniqueness, env consistency - **Code Generation** → verify build, tests, registration, patterns - **Deploy Review** → verify checklist completeness - **Refactoring** → verify build/tests before/after 2. Run **automated checks** (see `references/validation.md` for command-specific checks): ```bash # Core automated suite cd serverccn2 && ./gradlew compileKotlin 2>&1 | tail -5 # Build cd serverccn2 && ./gradlew test 2>&1 | tail -10 # Tests # Config checks for dir in serverccn2/configByMode/*/config/; do grep "db_prefix_key\|dao_type" "$dir/server.properties" done ``` 3. Run **spot-checks** (pick 3 random items from output): - Verify file paths exist - Verify counts match actual codebase - Verify config values match actual properties files 4. Classify failures by severity: - **CRITICAL** → fix immediately, re-run command - **WARNING** → flag to user, proceed with caveats - **INFO** → log for awareness 5. Generate **Validation Report**: ``` ## Validation Report — {command_name} | # | Check | Result | Severity | |---|-------|--------|----------| | 1 | Build compiles | PASS | — | | 2 | Tests pass | PASS | — | | ... **Overall: PASS / FAIL** ``` 6. Decision: - All PASS → proceed, save to memory - WARNING only → proceed with caveats noted - Any CRITICAL → stop, fix, re-validate - Multiple CRITICAL → re-run entire command from scratch --- ## Workflow Rules These rules apply to ALL commands: 1. **Read before write.** Always read existing source files before modifying them. Use Explore agents for broad scans, Read tool for specific files. 2. **Document before code.** Change order: - GDD first (if game rules change) - Tech Doc second (if architecture changes) - Code last 3. **User approval at every gate.** Present drafts and plans before writing. The user is the product owner. 4. **Preserve formatting.** When editing `.properties` files or JSON configs, **always preserve existing format, spacing, and comments**. 5. **Preserve consistency.** After every change, verify GDD ↔ Tech Doc ↔ Code alignment. 6. **Respect existing patterns.** Match code style already in the codebase: - Module pattern: Module.kt + RequestHandler + EventListener - Actor model for game rooms - GameCfg singleton for config - Exposed ORM for database - KSP for serialization 7. **Environment awareness.** When modifying configs: - Never use `dao_type=file` outside local dev - Ensure `db_prefix_key` is unique per environment - Validate DB node addresses - Check for single-point-of-failure risks 8. **Cross-project awareness.** Server changes may require: - MSerializer.js regeneration (`./gradlew run`) - ItemGroup.json update - Client code updates for new packets 9. **Save to memory.** After completing a command, save key findings and decisions to memory files for future sessions. 10. **Validate every output.** After every command, run `validate_result` automatically: - Automated checks: build, tests, config validation, counts, file paths - Spot-checks: 3 random items verified against actual codebase - Severity classification: CRITICAL (fix now), WARNING (flag), INFO (log) - CRITICAL failures block proceeding until fixed - See `references/validation.md` for command-specific validation checks --- ## Response Format - Tables for comparisons, inventories, and config audits - Bullet lists for action items and recommendations - Code blocks for file paths, commands, and snippets - Section headers for multi-part responses - Always state which command is executing and current step - For multi-command flows, state the pipeline upfront: > "Pipeline: `edit_server_idea` → `update_gdd` → `generate_server_code`" - Severity badges for config issues: `[CRITICAL]`, `[WARNING]`, `[INFO]` ## Quick Decision Guide | User Request | Command(s) | |---|---| | "Scan the server" | `scan_server` | | "Generate server tech doc" | `generate_server_tech_doc` | | "I want to add a new module" | `edit_server_idea` → `generate_server_code` | | "Create staging environment" | `manage_config` (4b) | | "Review config for production" | `manage_config` (4c) | | "Edit server.properties" | `manage_config` (4a) | | "Check server consistency" | `check_server_consistency` | | "Add new resource JSON" | `manage_resources` | | "Prepare for deploy" | `review_deploy` | | "Refactor payment module" | `refactor_server` | | "Is the server code matching GDD?" | `check_server_consistency` | | "Change win condition to 500 DIAMOND" | `edit_server_idea` → `check_server_consistency` | | "Compare all env configs" | `manage_config` (4c) | | "Validate last output" | `validate_result` | | "Check if scan is correct" | `validate_result` |