virtheart/TinyWaste
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
TinyWaste/docs/04-内容与数据字典.md
T
virtheart 2e1b58bada docs: 添加项目文档和图表文件 
添加游戏设计文档、技术架构文档、数值经济文档等内容
新增Mermaid图表文件描述系统架构和流程
包含README说明文档结构和阅读顺序
2026-04-28 19:19:20 +08:00

8.5 KiB
Raw Permalink Blame History

04 内容与数据字典

本文档定义新项目的“数据驱动内容”规范：字段含义、约束与复用策略。目标是让内容策划能够在不改代码的情况下扩展大部分内容，同时让程序具备稳定、可验证的数据接口。

4.1 总体约束

  • 所有配置都必须有 id（稳定、不可随意改名），并且支持本地化 name/desc。
  • 配置要可增量加载：按“基础数据 → 扩展包（DLC/活动）”分层，不互相覆盖时尽量追加。
  • 任何“逻辑分支”都尽量用配置表达（条件表达式、标签、权重表、效果链），避免硬编码。

4.2 通用结构

4.2.1 标签（Tags）

标签用于跨系统复用与筛选，避免重复字段：

  • 物品标签：food, water, medicine, scrap, tool, weapon, armor, ammo, quest
  • 地点标签：home, settlement, ruins, tunnel, forest, vault, radiated, safe
  • 事件标签：combat, trade, moral, hazard, story
  • 敌人标签：human, mutant, insect, beast, robot

4.2.2 条件（Condition）

用于事件/任务/配方/解锁等系统的统一条件表达：

  • 状态阈值：status.hunger >= 20
  • 物品拥有：inventory.has("water_purified", 1)
  • 科技完成：tech.has("water_filter_1")
  • 地点/标记：world.flag("met_mysterious_trader") == true
  • 时间：time.day >= 5 && time.hour >= 18

实现建议：条件采用受限表达式语言（DSL）或 JSON 结构化条件，避免 eval。

4.2.3 效果（Effect）

所有可配置结果尽量拆成原子效果并支持链式组合：

  • AddItem/RemoveItem
  • AddStatus（可正可负）
  • AddBuff/RemoveBuff
  • SetFlag（任务/世界标记）
  • UnlockRecipe/UnlockTech/UnlockPlaceService
  • StartCombat
  • Teleport
  • Log

4.3 物品（Item）

4.3.1 字段定义（建议）

字段 类型 必填 说明
id string 是 稳定唯一 ID
name string 是 显示名
desc string 否 描述文本
type string 是 food/material/tool/weapon/armor/ammo/quest/medicine
tags string[] 否 标签，用于筛选与规则复用
rarity string 否 common/uncommon/rare/epic
stackLimit number 否 堆叠上限，默认 1
volume number 否 占用体积，默认 1
durability {max:number} 否 耐久，存在则可损耗
effects Effect[] 否 使用后效果链（食物/药品等）
equipSlot string 否 weapon/head/body/foot 等
combat object 否 武器/护甲战斗参数
baseValue number 否 基础交易价值
craftable boolean 否 是否可制作（方便筛选 UI）

4.3.2 武器/护甲 combat 字段（建议）

  • 武器：
    • damageMin/damageMax
    • range
    • hitBonus
    • ammoType（可空：近战）
    • critChance/critMult
  • 护甲：
    • armor
    • dodgeBonus
    • radiationResist（可选）

4.3.3 物品效果（使用）

食物/药品/饮水等用 effects 表达，避免写死：

{
  "id": "water_purified",
  "name": "净水",
  "type": "water",
  "stackLimit": 10,
  "volume": 1,
  "effects": [
    {"type": "AddStatus", "status": "thirst", "value": 25},
    {"type": "AddStatus", "status": "radiation", "value": -2}
  ]
}

4.4 状态（Status）与阈值

4.4.1 字段定义

字段 类型 必填 说明
id string 是 hunger/thirst/energy/life/san/radiation 等
name string 是 显示名
desc string 否 说明
min/max number 是 上下限
value number 否 默认初值
decayPerMin number 否 每分钟自然变化（负数表示下降）
thresholds Threshold[] 否 阈值效果表

4.4.2 Threshold 定义

  • atOrBelow 或 atOrAbove
  • applyBuff / removeBuff
  • uiHint（用于提示玩家原因）

4.5 Buff/Debuff（Buff）

4.5.1 字段定义

字段 类型 必填 说明
id string 是 稳定唯一 ID
name/desc string 是 显示
type string 是 good/bad/neutral
durationMin number 否 持续分钟数，空表示永久直到清除
stack object 否 堆叠规则（maxStacks/refreshPolicy）
tickIntervalMin number 否 结算间隔
effects Effect[] 否 结算效果（例如每 10 分钟掉理智）
modifiers object 否 属性修正（命中/速度/消耗倍率）

4.6 配方与科技（Recipe / Tech）

4.6.1 配方（Recipe）

字段 类型 必填 说明
id/name string 是 标识
workbenchType string 是 hand/workshop/forge/cook/filter/med/lab
requirements Condition[] 否 条件集合
inputs {itemId:string,count:number}[] 是 消耗
outputs {itemId:string,count:number,weight?:number}[] 是 产出（可做权重表）
timeCostMin number 是 耗时
energyCost number 否 精力消耗
sideEffects Effect[] 否 副作用（辐射、疲劳等）

4.6.2 科技（Tech）

科技节点建议用“解锁能力”表达：

  • 解锁配方：unlockRecipes
  • 解锁地点服务：unlockServices
  • 永久修正：modifiers（例如制作耗时倍率 -10%）
  • 前置：requires（其他科技、状态阈值、完成任务）

4.7 地图与地点（Map / Place）

4.7.1 地点 Place

字段 类型 必填 说明
id/name string 是 标识
tags string[] 否 home/ruins/vault 等
dangerLevel number 是 0–10
services string[] 否 trade/rest/craft/heal/info
resourceNodes ResourceNode[] 否 可采集资源
trashNodes TrashNode[] 否 垃圾池
encounterTable EncounterEntry[] 否 遭遇权重表
eventPools string[] 否 事件池 ID（通用+地点专属）
questHooks QuestHook[] 否 任务触发钩子

4.7.2 路径 Edge

字段 类型 必填 说明
from/to string 是 起终点地点 ID
travelTimeMin number 是 基础耗时
risk number 否 途中风险修正（影响遭遇概率）
conditions Condition[] 否 需要某工具/科技才能通行

4.7.3 资源节点 ResourceNode

  • id/name
  • refreshMin：刷新/生长间隔
  • maxStock：最大存量
  • growsPerRefresh：每次生长数量
  • harvestCost：时间/精力/工具
  • outputs：产出物品权重表

4.7.4 垃圾节点 TrashNode

  • refreshMin
  • risk：触发负面事件概率加成
  • lootTable：掉落权重表

4.8 敌人（Enemy）

4.8.1 字段定义

字段 类型 必填 说明
id/name string 是 标识
tags string[] 否 类别标签
level number 否 用于难度缩放
life number 是 生命
attack {min:number,max:number} 是 攻击
armor number 否 护甲
range number 否 射程
hitRate number 否 命中
skills string[] 否 技能 ID 列表
lootTable LootEntry[] 否 掉落表

4.9 事件（Event）

4.9.1 字段定义

字段 类型 必填 说明
id string 是 事件 ID
tags string[] 否 combat/story/hazard 等
conditions Condition[] 否 触发条件
weight number 否 权重，默认 1
text string 是 主文本
options Option[] 否 选项列表（0–4）

Option：

  • text
  • conditions
  • check（属性检定配置，可选）
  • effects（成功/失败效果链）

4.10 任务（Quest）

4.10.1 字段定义

字段 类型 必填 说明
id/title string 是 标识
type string 是 main/side/dynamic
desc string 否 描述
prereq Condition[] 否 前置条件
steps QuestStep[] 是 阶段目标
rewards Effect[] 否 完成奖励
failConditions Condition[] 否 失败条件（可选）

QuestStep 支持目标：

  • ReachPlace
  • CollectItem
  • DefeatEnemy
  • CraftRecipe
  • TriggerEvent
  • SurviveDays

4.11 日志（Log）与可观测性

为了让系统可解释、可测试、可回放：

  • 所有关键变化都写日志：
    • 状态变化（原因、数值）
    • 战斗结果（命中/伤害/距离）
    • 事件结果（选项、成功/失败、消耗/获得）
    • 任务推进（步骤变化）
  • 日志结构化，支持筛选与上报：
    • timestamp
    • category
    • message
    • payload（可选）
Reference in New Issue View Git Blame Copy Permalink