JsonLoader 维基文档

生成器列表

以下是JSONLoader可用的生成器及相关资源：

额外资源

所有枚举类型（含模组）: https://github.com/SaxbyMod/SabyModEnums/wiki

印记配置（Configils）维基: https://docs.google.com/document/d/1QLAfomaTcatm-foU2P1ZoqGQFFvhCfmEnN4jIxAWceQ/edit?usp=sharing

动态立绘制作建议：使用https://www.pixilart.com/draw制作GIF并导出为精灵图！

官方JSONLoader维基: https://github.com/MADH95/JSONLoader/wiki

动态立绘

动态立绘是独立API，允许创建动态卡牌立绘。例如通过制作114x94像素的帧序列图，可使蜜蜂呈现飞行效果。文件存储为.json且无需后缀。

动态立绘示例

{
  "CardName": "Goat",         // 应用对象为黑山羊
  "Spritesheet": "MaidGoatAnim.png",  // 精灵图文件
  "FrameRate": 20,            // 20帧/秒
  "FrameCount": 10            // 共10帧
}

头目对话

头目对话也是独立的API，允许修改KCM（即凯茜模组）中任何头目的原始对话。文件扩展名为.json，后缀为_bd。基础字段如下：

矿工对话字段

钓鱼人对话字段

猎人/毛皮商对话字段

莱西对话字段

罗亚尔对话字段

对话示例

{
  "FileName": "KEVIN CLICK THIS!",        // 对话集合名称
  "Description": "MAKES THE BOSSES KNOW KEVIN!",  // 描述
  "Prospector": {                         // 矿工对话
    "BeforePickaxe": "Why do you always forget, KEVIN!",  // 替换挥镐前台词
    "AfterPickaxe": "TOO BAD, SO SAD, KEVIN!",            // 替换挥镐后台词
    "IfNoGold": "Damn, you remembered, I did not expect this!",  // 替换无金块台词
    "MuleKilled": "NOT MY MULE! WHY, KEVIN, WHY?"         // 替换骡子死亡台词
  },
  "Angler": {                              // 钓鱼人对话
    "GoFish": "FISH A NEW CARD!",          // 替换钓鱼台词
    "AimingHook": "THIS ONE SHALL DO!",    // 替换瞄准台词
    "EasyChoose": "I TAKE THIS LITTLE FISHIE",  // 替换选择台词
    "HookPull": "DID YOU REALLY JUST DO THAT?"  // 替换钩取台词
  },
  "TrapperTrader": {                       // 猎人/毛皮商对话
    "PrePhase2": "GOODBYE KEVIN *TRAP SHUTS*",  // 替换阶段切换前台词
    "Phase2": "HELLO KEVIN *BELL DINGS*",       // 替换阶段切换台词
    "PreTrade": "I SHALL TAKE THOSE FINE PELTS!",  // 替换交易前台词
    "Trade": "CHOOSE THE BEST, KEVY BOY!",        // 替换交易台词
    "PostTrade": "I WOULD HAVE CHOSEN BETTER, KEVIN!"  // 替换交易后台词
  }
}

卡牌制作

在JsonLoader中创建卡牌相对简单，只需在插件文件夹中新建一个.jldr2文件，并填入包含以下字段的JSON：

注：未包含的非必填字段通常默认为禁用状态。

卡牌JSON示例

{
  "name": "LFTD_Cicada", // 卡牌的代码内部名称
  "modPrefix": "LFTD", // 模组标识符
  "displayedName": "蝉", // 游戏内显示名称
  "description": "那永远惹人生厌的蝉，其嗡鸣声远至数里可闻。", // 莱西的介绍文本
  "metaCategories": [
    "ChoiceNode",
    "TraderOffer"
  ], // 赋予该卡牌ChoiceNode和TraderOffer元类别
  "cardComplexity": "Simple", // 设置为简单复杂度
  "temple": "Nature", // 指定为莱西的卡牌
  "baseAttack": 1, // 攻击力设为1
  "baseHealth": 1, // 生命值设为1
  "bloodCost": 2, // 消耗2点血祭
  "tribes": [
    "Insect"
  ], // 赋予昆虫族群属性
  "abilities": [
    "BuffEnemy",
    "LFTD.Swarm"
  ], // 赋予"惹人生厌"印记及模组新增的"蜂群"能力
  "tailName": "Tail_Insect", // 断尾时生成昆虫类尾巴
  "texture": "LFTD_Cicada.png", // 卡牌肖像图
  "emissionTexture": "LFTD_Cicada_emission.png" // 发光图层
}

卡包系统

此独立API允许通过KCM界面启用/禁用卡包，文件格式为无后缀的.jlpk。

卡包JSON示例

{
  "Title": "阿兹特克公会", // 卡包标题
  "Description": "这是阿兹特克人为提升游戏体验而创造的卡牌公会。", // 描述文本
  "ModPrefix": "AZTEC", // 关联的模组标识符
  "PackArt": "AZTECIAN_Pack_Icon.png", // 卡包图标文件
  "validFor": [ // 适用于所有冥刻者类型
    "LeshyPack",
    "P03Pack",
    "GrimoraPack",
    "MagnificusPack"
  ],
  "SplitPackByCardTemple": true // 按冥刻者类型拆分卡包
}

遭遇战配置

运作机制解析？本指南旨在提供帮助！

需要了解的关键事项：

• 保存遭遇战文件时必须以"_encounter.jldr2"结尾
• 记得检查json格式是否有效（推荐使用jsonlint网站验证）
• 使用自定义卡牌创建遭遇战时，需使用内部名称（包括前缀，例如：IGCC_Boar）

各组件独立运作说明：

地图枚举对照：

除非安装允许在最终头目前战斗的模组，否则Midnight、Midnight_Ascension和Pirateville均为冗余项。

配置示例：

{
  "name": "Example.BirdEncounter",
  //内部名称
  
  "minDifficulty": 1,
  //遭遇战出现所需最小进度（已失效，建议保持为1）
  
  "maxDifficulty": 32,
  //遭遇战停止出现所需最大进度（已失效，建议设为较高值）
  
  "regions": [
    "Alpine",
    "Forest"
  ],
  //遭遇战出现的地图区域（指定雪线和林地，仅出现在Prospector和Trapper/Trader地图）
  
  "dominantTribes": ["Bird"],
  //图腾战使用的族群类型
  
  "randomReplacementCards": [
    "Sparrow",
    "RavenEgg",
    "Porcupine",
    "AntFlying",
    "Cuckoo",
    "Adder",
    "Bee"
  ],
  //随机替换卡牌池
  
  "redundantAbilities": ["Flying"],
  //图腾战禁用能力
  
  "turns": [
    {
      "cardInfo": [
        //第一波次
        {
          //第一张卡
          "card": "Sparrow",
          //指定"麻雀"
          
          "randomReplaceChance": 50,
          //50%概率被randomReplacementCards池中的卡牌替换
          
          "difficultyReq": 15,
          //达到15级难度后替换原卡
          
          "difficultyReplacement": "Vulture"
          //满足等级要求后替换为"秃鹫"
        },
        {
          //第二张卡
          "card": "RavenEgg",
          "randomReplaceChance": 25,
          "difficultyReq": 10,
          "difficultyReplacement": "Raven"
        }
      ]
    },
    {
      //第二波次
      "cardInfo": [
        {
          "card": "Sparrow",
          "randomReplaceChance": 50,
          "difficultyReq": 15,
          "difficultyReplacement": "Vulture"
        },
        {
          "card": " ",
          //留空表示不放置卡牌，可用于隐藏卡牌直到满足特定条件
          "randomReplaceChance": 25,
          "difficultyReq": 10,
          "difficultyReplacement": "Raven"
        }
      ]
    }
  ]
}

留声机音轨配置

留声机音轨是JSONLoader中第二容易创建的要素，仅次于初始牌组（仅因需要制作/获取音轨文件）。文件应以.json为扩展名，并带有_gram后缀。

音轨配置示例

{
  "Prefix": "Saxby", // 定义音轨来源模组
  "Tracks": [ // 加载括号内的音轨
    { // 加载.wav格式音轨（半音量）
      "Track": "TestTrackA.wav",
      "Volume": 0.5
    },
    { // 加载.mp3格式音轨（全音量）
      "Track": "TestTrack2.mp3",
      "Volume": 1
    }
  ]
}

初始牌组配置

初始牌组是JSONLoader中最易创建的要素之一。牌组可包含任意数量卡牌（最低要求3张）。创建时需新建带_deck后缀的.jldr2文件，并按以下字段结构配置json：

牌组配置示例

详细配置示例如下：

{
  "decks": [ // 管理文件内所有牌组
    { // 注册测试牌组A
      "name": "TestDeckA", // 命名牌组A
      "iconTexture": "TestDeckA.png", // 设置牌组A图标
      "cards": [ // 管理牌组A的卡牌
        "AboveCurve", // 加入跑赢曲线
        "AnnoyTower", // 加入恼人广播站
        "DUMMY_5-5" // 加入第二幕的假人
      ]
    },
    { // 注册测试牌组B
      "name": "TestDeckB", // 命名牌组B
      "iconTexture": "TestDeckB.png", // 设置牌组B图标
      "cards": [ // 管理牌组B的卡牌
        "Goat", // 加入黑山羊
        "Moose", // 加入雄驼鹿
        "Grizzly" // 加入灰熊
      ]
    }
  ]
}

会说话的卡牌

本文将指导你如何使用JSONCardLoader制作具有对话功能的卡牌。

JSONCardLoader为会说话的卡牌提供以下功能支持：

• 自定义动态肖像
• 响应多种游戏事件的自定义对话内容
• 通过短音频文件添加自定义语音
• 支持在对话中切换面部表情

所有功能均通过JSON文件实现。你无需加载任何Unity预制件或类似资源——仅需准备若干图像文件并在JSON中引用即可。

准备工作

你需要基于一张已存在的卡牌进行改造。可使用JSONLoader创建新卡牌，具体说明请参阅JSONCardLoader的Thunderstore页面。

同时需要新建一个JLDR2格式文件，该文件需包含会说话卡牌的所有必要信息。此JSON文件名必须以"_talk.jldr2"结尾，否则将导致各类运行问题。

下文将详细解析"_talk.jldr2"文件结构。

文件结构

强烈建议使用此JSON生成器创建你的JSON文件。该生成器的JSON模式经过专门设计，包含详尽描述和模式匹配功能以简化流程。

再次强调，强烈推荐使用该JSON生成器：链接。

标准JSON文件结构如下：

{
  "cardName": "",
  "faceSprite": "",
  "eyeSprites": {
    "open": "",
    "closed": ""
  },
  "mouthSprites": {
    "open": "",
    "closed": ""
  },
  "emissionSprites": {
    "open": "",
    "closed": ""
  },
  "faceInfo": {
    "blinkRate": 1.5,
    "voiceId": "female1_voice",
    "voiceSoundPitch": 1,
    "customVoice": ""
  },
  "emotions": [
  ],
  "dialogueEvents": [
    {
      "eventName": "OnDrawn",
      "mainLines": [ "" ],
      "repeatLines": [
        [ "" ],
        [ "" ]
      ]
    }
  ]
}

各字段详解见下文。完整示例可参考Talking Possum卡牌文件，该示例包含动态肖像、对话代码和自定义语音。

向后兼容性说明

已对原TalkingCardAPI模组创建的卡牌提供兼容支持。除新增的"emissionSprites"字段（旧版使用单图"emissionSprite"字段）外，多数字段保持相同。建议迁移至新结构。

字段总览

图像规格

所有面部图像（包括眼睛、嘴巴和发光效果）尺寸需符合《邪恶冥刻》第一章卡牌肖像标准：114×94像素。

建议使用分层绘图软件分别绘制面部、眼睛和嘴巴，并单独导出各图层。

同一图像重复使用不会影响性能（详见此节）。

可用_表示空纹理，用于隐藏面部特定部位（详见此节）。

FaceInfo配置

控制角色面部动画细节：

“voiceId”仅限以下三种取值：

1. female1_voice
2. cat_voice
3. kobold_voice

多数游戏内卡牌使用第一种并通过调整音调实现变化。

自定义语音

可通过“customVoice”字段指定音频文件路径（支持MP3/WAV/OGG/AIFF格式）。建议使用极短的元音音频片段，因其将被快速重复播放。

当“customVoice”非空时，“voiceId”字段将被忽略。

对话事件

“dialogueEvents”为对话事件对象数组。建议使用前文提到的生成器简化配置。

每个对话事件对象包含以下字段：

事件触发器

有效“eventName”取值及说明：

主对话内容

“mainLines”包含首次触发时播放的文本内容。同一存档中仅播放一次。

如需重复播放，可将内容置于“repeatLines”数组中。

循环对话内容

“repeatLines”为二维数组结构，包含多组循环播放的对话文本。示例：

"repeatLines": [
  [
     "这是第一组有效对话",
     "这组对话结束于此"
  ],
  [
     "这是第二组有效对话",
     "这组对话又结束于此"
  ]
]

如果您仍然不清楚它们的工作原理，我强烈建议您使用我上面链接的JSON生成器。我为其编写的JSON架构完全支持添加循环的对话文本。

对话代码

《邪恶冥刻》对话事件中一项精妙的设计是对话代码（dialogue codes），它们能为对话注入鲜活的表现力！

以下将重点解析与可对话卡牌最相关的对话代码。所有代码均适用于可对话卡牌。

等待（[w:])

这是使用频率最高的对话代码，也是游戏本体在所有对话中最常调用的功能。

“[w:x]”代码会在语句后续部分播放前插入x秒的暂停。

使用示例：

"哈喽。[w:1]你呢？"  

此例中，角色说完“哈喽”后会等待1秒，再继续“你呢？”。

秒数不必为整数。例如使用“[w:0.2]”实现0.2秒短暂停顿是合法操作，且在原版游戏对话中频繁出现。

需注意的是，建议不要使用低于[w:0.1]的数值，因为尚不清楚该参数的最小有效阈值（况且更短的停顿也无实际意义）。

颜色（[c:])

[c:]代码用于改变局部文本颜色。

使用示例：

"[c:R]这段文字是红色。[c:] 这段恢复默认色。"  

此例中，[c:R]之后的内容会切换为代码“R”对应的红色，而[c:]之后则恢复默认文本颜色。其机制可理解为“开启”彩色文本模式后再“关闭”。

“如何获取各颜色对应代码？”
无需担忧！以下是完整的颜色代码对照表：

（注：这些是游戏内置的预设颜色，非本人选定。确实是个非常古怪的色系组合。）

自定义颜色

本模组新增了通过对话代码使用自定义颜色的功能。只需将上表中的颜色代码替换为十六进制颜色码，模组便会将其解析为可用文本颜色。

示例：

"你肯定...[w:0.4][c:#7f35e6]很困惑[c:][w:1]了。"  

此例中“很困惑”三字会显示为#7f35e6色值（若不想查证，即此色）。

请注意：为确保兼容性，十六进制代码必须包含#符号。

莱西对话（[leshy:x]）

[leshy:x]代码会触发莱西说出x内容。该功能非常适合制造莱西与卡牌之间的互动效果！

使用示例：

"我们完了。[leshy:安静。][w:2]"  

此例中，角色说完"我们完了"后，莱西立即接话"安静。"，文本将持续显示2秒。

关键注意事项：

1. 莱西的台词无需额外添加引号
2. “等待”代码仍适用于莱西的台词

情绪系统

原版所有可对话卡牌都具备多套情绪状态。情绪即字面含义：通过不同面部表情传递角色情感。

技术细节：情绪在游戏代码中是以C# enum实现的枚举类型，每个枚举项都有对应的数字编号。

角色的默认情绪是“Neutral”（中立），该状态会自动加载。

完整情绪列表及对应编号：

枚举中还存在“None”项，但建议避免使用。

• 添加情绪方法参见此章节
• 使用情绪方法参见此章节

添加情绪

通过在JSON文件的“emotions”数组中添加新项来扩展情绪系统。标准格式如下：

"emotions": [  
  {  
    "emotion": "Anger",  
    "faceSprite": "Example_AngryFace.png",  
    "eyeSprites": {  
      "open": "Example_AngryEyes_Open.png",  
      "closed": "Example_AngryEyes_Closed.png"  
    },  
    "mouthSprites": {  
      "open": "Example_AngryMouth_Open.png",  
      "closed": "Example_AngryMouth_Closed.png"  
    },  
    "emissionSprites": {  
      "open": "Example_AngryEmission_Open.png",  
      "closed": "Example_AngryEmission_Closed.png"  
    }  
  }  
]  

此例添加了名为“Anger”的新情绪，并配置了对应的面部素材。

“emotion”字段必须使用有效情绪名称（参见前表）。

"必须替换所有素材吗？"

并非必须替换全部素材！

可仅修改需要变更的字段，未声明字段将自动继承Neutral情绪的对应素材。

示例：

"emotions": [  
  {  
    "emotion": "Anger",  
    "eyeSprites": {  
      "open": "Example_AngryEyes_Open.png",  
      "closed": "Example_AngryEyes_Closed.png"  
    },  
    "emissionSprites": {  
      "open": "Example_AngryEmission_Open.png",  
      "closed": "Example_AngryEmission_Closed.png"  
    }  
  }  
]  

此例仅修改了眼部素材和发光效果，面部与嘴部素材仍保持Neutral状态。

若仍有困惑，建议使用前文提到的JSON生成器工具。该工具支持字段可选配置，特别适合情绪系统搭建。

附注：素材复用

“我想重复使用同一张图片！会影响性能吗？”

本模组实现了纹理缓存机制，确保同一图片无论被引用多少次都仅加载一次。因此无需担忧素材复用问题。

这意味着你可以安全地在多个情绪（甚至多个角色）间复用眼部等素材，不会产生性能损耗。

附注：空白纹理

若需隐藏某个部件（如关闭发光效果），可用下划线_代表完全透明的空白纹理。

示例：

{  
  "emotion": "Quiet",  
  "eyeSprites": {  
    "open": "Example_QuietEyes_Open.png",  
    "closed": "Example_QuietEyes_Closed.png"  
  },  
  "emissionSprites": {  
    "open": "Example_QuietEmission_Open.png",  
    "closed": "_"  
  }  
}  

此例中，闭眼时的发光效果被隐藏。该技巧特别适用于眼部发光等场景。

同理可用于隐藏嘴部、完全关闭发光等各类需求。

使用情绪

通过[e:x]对话代码切换情绪状态，其中x为情绪名称（参见前表）。

模组已实现情绪名称大小写不敏感，以下写法等效：

"[e:Anger]我很生气。"  
"[e:anger]我很生气。"  
"[e:AnGeR]我很生气，我的键盘也在搞我。"  

也可直接使用数字编号：

"[e:2]我很生气。"  

常见问题

问： “加载_talk.jldr2文件时报错！如何解决？”

答： 请检查JSON文件语法是否正确。推荐使用JSONLint等在线校验工具排查问题。