From 189e5fcff4d82572f5640015e0f9d792c75b3dd1 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 14 Feb 2026 11:27:35 -0500 Subject: [PATCH] Define overworld chunk/zone/region plan and live editor client contract --- Future_plan.md | 232 +++++++++++++++++++++++++++++++++++++++ pending-clientChanges.md | 35 ++++++ 2 files changed, 267 insertions(+) create mode 100644 Future_plan.md diff --git a/Future_plan.md b/Future_plan.md new file mode 100644 index 0000000..4f8a444 --- /dev/null +++ b/Future_plan.md @@ -0,0 +1,232 @@ +# Future Plan + +## Objective +Define the next major gameplay and platform systems: +1. NPC framework (combat + non-combat + shops + dialog/quests). +2. Party + clan systems. +3. Party XP sharing. +4. Overworld runtime + browser/in-game world editing with VIP-gated build areas. +5. Player spell system (separate from mob abilities), with learning requirements and hotbar integration. + +--- + +## Workstream 1: NPC System + +### Scope +1. Add NPC entity model with behavior modes: + - passive + - aggressive + - retaliate-on-hit + - killable / non-killable +2. Reuse combat foundation (stats, resistances, cooldowns, combat state), but keep NPC-specific behavior profiles. +3. Support optional attachments per NPC: + - shop/trade profile + - dialog tree root + - quest giver hooks + +### Data Model (Draft) +1. `NpcDefinition` + - identity, faction, behavior mode, killable flag, respawn config + - stat block, equipment/loot profile, spell/ability loadout for retaliation/combat +2. `NpcSpawn` + - world/dungeon context, x/y, conditions, schedule +3. `NpcShopProfile` + - stock entries, prices, buy/sell rules, refresh behavior +4. `NpcDialogNode` + `NpcDialogEdge` + - branching text, requirements, rewards, quest state transitions + +### Milestones +1. M1: NPC spawning + core AI/combat + retaliation. +2. M2: Shop/trade interactions. +3. M3: Dialog tree runtime + quest hooks. + +--- + +## Workstream 2: Party + Clan System + +### Party +1. Party lifecycle: + - invite, accept, leave, kick, disband, leader transfer +2. Shared state: + - member list, leader id, optional role tags +3. Runtime support: + - proximity checks, shared dungeon entry, party chat channel + +### Clan +1. Clan lifecycle: + - create, invite, join, leave, remove, rank/role management +2. Shared systems: + - clan roster, MOTD, permissions, clan chat +3. Future-ready extension: + - clan progression/perks (deferred) + +### Milestones +1. M1: Party backend + party UI + chat. +2. M2: Clan backend + role permissions + chat. +3. M3: Party/clan hooks in dungeon and overworld systems. + +--- + +## Workstream 3: Party XP Sharing + +### Rules (Initial) +1. XP source events are tagged with killer + eligible nearby party members. +2. Split XP by party size with configurable efficiency curve. +3. Add anti-abuse checks: + - proximity radius + - minimum contribution or activity +4. Add optional bonus multipliers by party size. + +### Config +1. `PartyXpShareEnabled` +2. `PartyXpShareRadius` +3. `PartyXpEfficiencyBySize` (array/map) +4. `PartyXpBonusBySize` (array/map, optional) + +### Milestones +1. M1: Server-side XP split logic. +2. M2: Combat log + UI feedback per member. +3. M3: Balance pass on scaling curve. + +--- + +## Workstream 4: Overworld + Editing + VIP Build Gate + +### Overworld Runtime +1. Persistent map/chunk model using `region -> zone -> chunk`. +2. Overworld entity simulation (players, NPCs, mobs, objects). +3. Cross-zone travel and persistence checkpoints. + +### World Sizing (v1 Defaults, Configurable) +1. Chunk size: `64x64` tiles. +2. Zones per region: `4x4` zones (`16` zones total). +3. Chunks per zone: `8x8` chunks (`64` chunks per zone). +4. Region footprint: `32x32` chunks (`2048x2048` tiles at 64px chunks). +5. Runtime config keys: + - `World.ChunkWidthTiles`, `World.ChunkHeightTiles` + - `World.ZonesPerRegionX`, `World.ZonesPerRegionY` + - `World.ChunksPerZoneX`, `World.ChunksPerZoneY` +6. Hard requirement: bounds and coordinate conversion must be server-authoritative. + +### Editing Surfaces +1. Browser editor: + - admin/world-authoring controls, tile/object/NPC placement + - select region + zone + chunk, or load full zone edit mode + - region minimap outline showing all zones, with selected zone/chunk highlighted +2. In-game editor: + - restricted build mode with safe action logs and undo windows + +### Browser Live Editor Requirements +1. Tile placement: + - pick sprite sheet + - pick frame/tile + - set `isWalkable` (bool) + - set `isInvisiblePaywall` (bool) +2. Object placement: + - pick object definition (filterable search) + - place/move/remove +3. NPC placement: + - pick NPC definition (filterable search) + - place/move/remove +4. Edit transport: + - use existing proximity update model for delta broadcasts + - edits apply as chunk-scoped change batches with monotonic version + - support explicit resync snapshot per chunk/zone +5. Safety: + - server validates all writes (bounds, permission, definition IDs) + - audit log for every edit operation (who/where/what). + +### VIP Paywall Barrier +1. Add an invisible barrier tile/object type and tile flag (`isInvisiblePaywall`). +2. Entry/build permission checks: + - allow if player is VIP or explicitly whitelisted + - deny with clear client feedback if not allowed +3. Region-level policy: + - per area `BuildAccessMode` (public, vip_only, whitelist_only) + +### Milestones +1. M1: Overworld chunk load/save loop. +2. M2: Browser editor core (tile/object/NPC + chunk selector + zone minimap). +3. M3: Live delta sync hardening (versioned chunk updates + resync path). +4. M4: In-game editor + permission model. +5. M5: VIP barrier/paywall enforcement + admin tooling. + +--- + +## Workstream 5: Player Spell System (Separate from Abilities) + +### Design Direction +1. Player spells are a separate system from mob abilities. +2. Spell categories: + - combat + - enchantment + - buff + - debuff + - summon +3. Spells are learned through requirements: + - required item(s) + - required stat thresholds + - optional class/faction/quest gates + +### Runtime Requirements +1. `SpellDefinition` + effect payload schema. +2. `PlayerLearnedSpell` tracking with source and timestamp. +3. Cast pipeline: + - cost checks + - cooldown/global cooldown checks + - target validation + - effect application +4. Hotbar integration: + - drag/drop assignment + - cooldown display + - lockout/error messaging + +### Milestones +1. M1: Spell data model + learning requirements. +2. M2: Cast runtime + networking + hotbar wiring. +3. M3: First spell packs (combat + buff/debuff + summon). +4. M4: Enchantment and advanced conditional spell behaviors. + +--- + +## Cross-Cutting Requirements + +### Admin Tooling +1. NPC editor (stats/behavior/shop/dialog links). +2. Party/clan moderation tools. +3. Overworld region editor with access policy controls. +4. Spell editor + requirement rule builder. + +### Telemetry / Audit +1. Track economy events (shop buys/sells, quest rewards). +2. Track party XP distribution. +3. Track in-game editing operations (who, what, where, when). +4. Track spell learn/cast metrics and failures. + +### Security / Abuse Prevention +1. Server-authoritative validation for all permissions and cast rules. +2. Rate limits on invites, chat, shop operations, and spell casts. +3. Explicit anti-cheat checks for world editing and VIP barrier bypass attempts. + +--- + +## Suggested Delivery Order +1. NPC core + retaliation combat. +2. Party system + XP sharing. +3. Clan system. +4. Spell framework + learning + hotbar. +5. Overworld runtime base. +6. Browser editor, then in-game editor. +7. VIP build/paywall barriers and region policy hardening. + +--- + +## Open Design Decisions +1. Should non-killable NPCs still enter combat animation/state when attacked, or only retaliate with non-lethal behavior? +2. Party XP model preference: + - equal split + - weighted by contribution + - hybrid +3. Clan feature depth for v1: chat + roster only, or include progression/perks immediately? +4. Overworld editor authority: admin-only at launch, or delegated trusted roles? +5. Spell learning consumption: should required item be consumed on learn or only checked as prerequisite? diff --git a/pending-clientChanges.md b/pending-clientChanges.md index a3c764f..4464744 100644 --- a/pending-clientChanges.md +++ b/pending-clientChanges.md @@ -63,3 +63,38 @@ - `STASH_DEPOSIT` (`612`) - `STASH_WITHDRAW` (`613`) - `STASH_RESULT` (`614`) + +## Overworld Live Editing (Planned) + +- Browser editor needs world hierarchy selection: + - region -> zone -> chunk + - optional full-zone load mode +- Region minimap support: + - zone outlines for the full region + - selected zone/chunk highlight + +### Tile editing requirements + +- Tile picker flow: + - select sprite sheet + - select frame index + - set `isWalkable` (bool) + - set `isInvisiblePaywall` (bool) +- Live placement and erase should apply immediately via proximity-safe delta updates. + +### Object/NPC editing requirements + +- Place/move/remove object instances from filterable definition lists. +- Place/move/remove NPC spawns from filterable NPC definition lists. +- Changes should be chunk-scoped and include version numbers to prevent stale overwrites. + +### Proposed payload additions + +- Chunk state payload: + - `regionId`, `zoneId`, `chunkX`, `chunkY`, `version` + - `tiles[]` with `{ x, y, sheetId, frameIndex, isWalkable, isInvisiblePaywall }` + - `objects[]` with placement + definition id + - `npcs[]` with spawn placement + npc definition id +- Delta update payload: + - `regionId`, `zoneId`, `chunkX`, `chunkY`, `fromVersion`, `toVersion` + - operations list (tile upsert/remove, object upsert/remove, npc upsert/remove)