dst-mod-creater

name	dst-mod-creater
description	饥荒联机版(Don't Starve Together) Mod 全栈开发技能。适用于任何与 DST mod 相关的任务：新地皮/地形/生物群系、新建筑/道具/武器/食物、新生物/Boss、世界生成改造、自定义UI/HUD、组件扩展、配方与科技、角色、汉化、美术资产管线(tex/xml/anim)。包含基于 DST 官方源码(4044文件)、10 个大型 mod(棱镜/热带体验/神话书说/Uncompromising/道诡异仙/登仙/丰耘秘境/山海秘藏/万物书/地府, 共2.7GB) 和 7 个官方模板(含人物模板 esctemplate 的部位/动画/皮肤标准) 的学习笔记、API 参考、可复用模板。触发词: 饥荒mod、DST、饥荒联机、饥荒地皮、饥荒建筑、饥荒生物、饥荒人物、饥荒角色、角色皮肤、人物动画、饥荒mod开发、饥荒源码。

dst-mod-creater — 饥荒联机版 Mod 开发技能

基于 DST 官方 Lua 源码全量学习 + 10 个大型 mod 逆向学习 + tex/xml 美术管线破解 构建的可移植技能包。核心知识都在本目录内，离线可用。

工作流（写代码前必须执行）

1. 读需求 → 确定 mod 类型（地皮/建筑/生物/道具/系统）
2. 读对应参考（先读后写，不要凭记忆）：
   • 地皮/地形/世界生成 → references/api-worldgen.md + references/art.md
   • 建筑/道具/配方 → references/api-prefabs-af.md + references/api-prefabs-gm.md + references/api-core.md（Recipe2）
   • 生物/AI → references/api-prefabs-nz.md + references/api-ai.md
   • 组件扩展 → references/api-components-ag.md / -hp.md / -qz.md
   • UI/HUD → references/api-ui.md
   • 人物/角色/皮肤 → references/character-esc.md + references/official-templates.md
   • 参考大 mod 做法 → references/mod-notes/
3. 选模板 → templates/ 起步（每个模板都是可运行骨架，API 已验证）；人物从 templates/official/extended sample character-DST/ 复制（官方标准）
4. 写代码 → 按模板扩展；数值走 TUNING；文本走 STRINGS
5. 校验 → Lua 语法检查（luaparser 或 luac -p）；资产命名与 prefab 引用一致；纹理 2 的幂

快速上手（30 分钟出一个新地皮+新建筑）

templates/modinfo.lua     → 复制改名字
templates/modmain.lua     → 复制，改 prefab 名
templates/turf.lua        → 新地皮（含生物群系挂载）
templates/building.lua    → 新建筑（含配方）
templates/item.lua        → 新道具
templates/creature.lua    → 新生物（prefab+brain+stategraph 三件套）
templates/worldgen.lua    → 世界生成扩展
templates/ui.lua          → 自定义 HUD
templates/official/       → 7 个 Klei 官方模板（人物用 extended sample character-DST）

核心事实（每条都要遵守，出处见 references）

• Recipe2 是唯一推荐配方写法：mod 沙箱里用 AddRecipe2(name, ingredients, tech, config, filters)（modutil.lua:732，第 5 参可选，把配方追加进额外制作栏）；Recipe 旧 positional 参数已废弃
• Prefab 骨架铁律：CreateEntity → 实体组件(Transform/AnimState/Network...) → 标签 → SetPristine() → if not TheWorld.ismastersim then return inst end → 服务端组件
• 地皮是动态注册的：现代 DST 无 tiles.lua，TileManager.AddTile（mod 里用 modutil 的 AddTile 钩子）注册，ID 自动分配进 WORLD_TILES；旧 GROUND 常量 deprecated
• HUD 挂载点：ThePlayer.HUD.controls（playerhud.lua:915）；旧版 FindWidget/AddClassified 不存在，别用
• 铺地皮：TheWorld.Map:SetTile(coords, GROUND_NAMES.xxx)，会清 undertile 下层数据
• 网同步三件套：AddNetwork → SetPristine → ismastersim 分界；跨端数据用 net_* 变量或 replica 组件
• 事件：ListenForEvent(event, fn, source)；RemoveEventCallback 必须传原 fn（entityscript.lua:1223）
• TUNING 覆盖：mod 改平衡用 TUNING.xxx = 值（metatable 链：TUNING → TUNING_MODIFIERS → ORIGINAL_TUNING）
• 技术值：FSM 组件用 inst:StartUpdatingComponent(comp)；长任务用 DoTaskInTime/DoPeriodicTask；时间单位 FRAMES=1/30 秒

美术资产管线（详见 references/art.md）

• tex 格式已破解（KTEX magic + DXT5/DXT1）：格式布局、解码器在 references/art.md 第 1 节
• 尺寸规范：2 的幂（64/256/512/1024），图标 64x64，地皮纹理 1024x1024，UI 面板 512-2048
• 格式：DXT5 占 95.7%（带 alpha），全 mipmap 链
• XML 图集：单纹理图集为主（一物一图集）；tile 图集 <Element name="tileID" .../>
• 零美术成本技巧：直接引用官方纹理 data/DLC0002/levels/tiles/jungle.tex 重排 UV 造新地皮（神话书说/登仙实证）
• 动画：anim/*.zip（build.bin + anim.bin + atlas-0.tex），命名规范见 art.md 第 6 节
• tex 双格式：DXT5 占主流（95.7%）；官方人物模板是 8-bit RGBA 无压缩（数据区大小 == wh4，判定法见 art.md §1.1），ktex_decode 已支持

人物美术标准（官方 esctemplate，详见 references/character-esc.md）

硬性规则：新角色一律以 templates/official/extended sample character-DST/ 为底图/标准——20 部位全覆盖、动作齐全、尺寸不得偏离下表。

用途	硬尺寸（来源 templates1/2）
角色动画贴图（Spriter 导入原图）	1024x512 RGBA
存档槽头像 saveslot	120x104
选人界面头像 selectscreen	188x284
选人大肖像 bigportrait	1024x1024 RGB
小地图/头像 avatars	64x64
名称横幅 names	876x434

• 20 部位规范：face(33帧200x200)/headbase(4,300)/hair(4,400)/torso(11,160x120)/foot(8,100)/hand(20,100)/leg(11,60x80)/arm_lower(7)/arm_upper(7,80)/cheeks(2,64x60)/hair_hat(4)/headbase_hat(4)/hairpigtails(5,250x300)/skirt(5,160x120)/tail(12,250x100)/hairfront(2)/arm_upper_skin(3)/torso_pelvis(11)/SWAP_ICON(1,268x244)/face_sail(1)。保持官方帧数与 pivot，只换像素（全表+pivot 在 character-esc.md §10）
• 风格：灰度铅笔线稿为主 + 局部着色（torso/skirt/hairpigtails）；幽灵 build 白色 + 雾特效
• 生成流程：复制模板 → 替换 esctemplate 名 → 按部位表重绘 → Spriter 装配 → autocompiler 编译 → names_[char].xml 的 Element name 必须改 [char].tex（否则选人界面无名）→ 游戏内验证（详见 character-esc.md §14）
• 工具：tools/scml_analyze.py（导出部位规范）、tools/char_sheet_gen.py（生成空白 1024x512 贴图模板 + 尺寸校验）；样本见 assets/official/

汉化与多语言

• 文本集中在 modinfo.lua 的 L 表 + 代码内 STRINGS 表
• STRINGS 结构：STRINGS.NAMES.XXX / STRINGS.RECIPE_DESC.XXX / STRINGS.CHARACTERS.GENERIC.DESCRIBE.XXX / STRINGS.ACTIONS.XXX
• 官方字符串结构参考 references/api-core.md（strings.lua 说明）
• 翻译文件：.pot + translator.lua 机制；mod 里用 GetModConfigData 读 locale 或直接按 L.name[locale] 模式

代码规范

• 注释：极简中文注释，参照官方风格（文件头说明 + 关键点）
• 命名：prefab 名小写蛇形（mybuilding）；tile 名 snake_case；turf 物品 turf_ 前缀
• 数值：集中放 TUNING.XXX 或 mod 自己的常量表，不要散落 magic number
• 服务端逻辑必须 if not TheWorld.ismastersim then return end 守卫
• 存档：OnSave(data, refs) 只存差异；GUID 引用用 refs 表恢复

references/ 索引

文件	内容
api-core.md	根目录 218 文件全览；modutil 全部钩子表；Recipe2/事件/Action/Prefab API；地皮注册
api-components-ag.md	组件 a-g（292个）；组件骨架/序列化/世界组件模式
api-components-hp.md	组件 h-p（240个）；Map:SetTile/铺地皮/建筑组件装配
api-components-qz.md	组件 q-z（288个）；workable/terraformer/升级建筑
api-prefabs-af.md	prefab a-f（479个）；植物/树/火堆/农场模板
api-prefabs-gm.md	prefab g-m（364个）；建筑 12 例精读/施工建筑/容器
api-prefabs-ho.md	prefab h-o 补充精读（183个）；海难毒/湿度/氧/船特性移植
api-prefabs-nz.md	prefab n-z（530个）；生物模板
api-ai.md	stategraph/brains/behaviours 全量；状态机与行为树
api-worldgen.md	地皮系统/task/room/layout/scenario 全链路；官方示例
api-ui.md	widgets/screens 全量；HUD 定制/Widget API
art.md	tex 格式破解(DXT5+RGBA8)/统计/色板/XML atlas/tile 图集/动画命名
official-templates.md	7 个 Klei 官方模板总览：素材包硬尺寸/static layout/钩子/最小 prefab/音效
character-esc.md	官方人物模板 esctemplate：人物标准（代码/18 项资产/20 部位/SCML/皮肤/生成工作流）
mod-notes/mod-legion.md	棱镜：hook 模式/配表驱动/新科技站 + 专题：21种特色植物/雨硫岛/噪声地皮
mod-notes/mod-mythwords.md	神话书说：loader 架构/零美术成本地皮/动画规范 + 专题：蟠桃人参果葫芦/广寒宫方寸山
mod-notes/mod-dengxian.md	登仙：修仙系统/境界锁/replica 对 + 专题：29种灵草仙树/8+秘境/丹药配方映射
mod-notes/mod-tropical.md	热带体验：海难哈姆雷特生态移植/域外海洋世界(kindofworld==20)/29新tile/椰树竹子咖啡
mod-notes/mod-tropical-prefabs-ag.md	热带体验 prefabs A-G 补充精读（337文件）：windy/goddess/gold系/水下生态
mod-notes/mod-uncompromising15.md	Uncompromising 1.5：tile_adder/环境威胁 + 专题：28种植物/毒草陷阱/环境联动
mod-notes/mod-daogui.md

工具集（tools/）

逆向/资产解码实用工具（KTEX 解码、批量像素统计、DaxSg/LOL! 混淆解密管线），说明见 tools/README.md。

校验清单（交付前）

• Lua 语法：luac -p 或 luaparser 通过
• 每个 prefab 在 modinfo.PrefabFiles 或 modmain 声明
• 配方引用的 prefab/placer/图标存在
• 资产路径（anim/zip 名、images/atlas 名）与文件名一致
• 纹理尺寸 2 的幂，DXT5
• 服务端守卫齐全，客户端无逻辑
• STRINGS 覆盖 NAMES/DESCRIBE/RECIPE_DESC
• 人物：AddModCharacter 的 18 项资产齐全（saveslot/selectscreen+silho/bigportraits/avatars×3/map_icons/names+gold/modicon）
• 人物：names_[char].xml 的 Element name 已改为 [char].tex
• 人物：贴图尺寸符合硬标准（1024x512 / 120x104 / 188x284 / 1024x1024）
• 人物：anim zip 含 build.bin+anim.bin+atlas；20 部位帧数/pivot 与官方一致