Overview
官方英文文档的粗翻中文版。
本指南已停更，最新版文档翻译请见100%鲜橙汁中文wiki。
以下为初版文档翻译（2020.9.18版）
欢迎！
欢迎来到这个全新的指南，它将指导你安装和创建各种各样100%鲜橙汁的mod。
如果你在任何时候有任何问题，你都可以来到我们的Discord modding channel[discord.com]，创意工坊讨论区，或者这个指南（英文文档链接）的评论区。
你可以从“创建您的第一个mod”小节开始。
在Steam创意工坊查看100%鲜橙汁mod:
[link]
【个人能力有限，若能有大佬帮忙，欢迎联系我或在评论区留言QAQ】
法律声明
本说明中描述的游戏资源只能在游戏本身之外提取和使用，仅能用于为《100% Orange Juice》创建自定义的图形mod。它们不能用于任何其他目的，也不能以任何方式侮辱诋毁游戏或角色们，或侵犯版权所有者的权利。所有mod创作者都有责任遵守当地法律和尊重商标。
Fruitbat Factory,Ltd.可以通过在Twitter，Discord，Steam或其他公共平台上发布有关这些游戏资源的公告，来宣布对这些游戏资源的使用方式进行进一步的限制，或撤销使用这些资源来创建mod的权利，并且加密列出的图形档案。
在公布任何mod之前，创建者都有责任参考这个文档的最新版本，以确保他们的mod与当前的mod指南和资源使用限制兼容。
局限性
当前已可修改单元（Unit）和卡图、背景音乐、角色语音以及音效。
贴图位于units、alphamasks、hats、hairs、和cards等游戏压缩包中。（提示：压缩包位于游戏根目录的data文件夹中，你可以用任意解压软件打开它们，如：7-Zip、WinRAR、WinZIP……）
在设置界面新添加的Mods选项中可以查看结果。
系统版本
===============================
创建你的第一个Mod
启动游戏后，“mods”文件夹会出现在与100%鲜橙汁的游戏启动程序同一个目录的位置。你可以通过在Steam库中>右键单击100％鲜橙汁>属性>本地文件>浏览本地文件找到它。（或者是在Steam库中>右键单击100％鲜橙汁>管理>浏览本地文件。）
mods文件夹将会是你存放所有mod的地方。
要创建一个新mod，只需要在“mods”文件夹中新建一个文件夹。请尽可能使用简单的名字。这将是你放置你的mod资源和定义的地方。
自从100%鲜橙汁的Steam创意工坊大更新后，我们已采用了一种新的格式创建mod。
我们现在使用JSON来解析mod数据，它重新定义了创建mod的整个过程。
这也将是今后唯一支持方法，如果你希望将你的mod上传到Steam创意工坊，则必须采用此方法。
下方是使用示例。
{ “ModDefinition”: { “name”: “Cuties Ft. Sora Alone”, “description”: “loved mod”, “author”: “Sora [Fruitbat Factory]”, “system_version”: 2, “changelog”: “Initial release.” }, “ModReplacements”: { “textures”: [ “units/cuties_00”, “units/cuties_01”, “units/cuties_02” ], “music”: [ { “unit_id”: “sorasp”, “file”: “music/grayhued”, “loop_point”: 796411 } ] } }
之后，必须使此文件位于你的mod文件夹的根目录下，并命名mod.json
若想要查看旧版制作mod定义的方法，请查阅相关章节。但建议你请一定要坚持使用新版格式！
发布你的mod至创意工坊
为了将你的mod发布至Steam创意工坊，你必须确保满足以下条件：
- 你的mod定义文件必须使用JSON格式。
- 你的mod必须有一个有效的预览。跳转至自定义预览章节了解更多信息。
一旦满足条件，你就可以前往游戏中选择发布（Publish）。
如果在上传过程中发生错误，会跳出一条消息告诉你更多情况。
mod上传完成后，你就会被重定向到你的创意工坊发布物品页面，准备供所有人使用。
请注意，在默认情况下你的所有发布物都会被设为公开。
Mod定义章节
此部分与旧版本不兼容。
name
string
你的mod的名字，用于在mod列表展示。同时也是你创意工坊中物品的标题。
✓
description
string
你的mod的描述，用于在mod列表展示。同时也是你创意工坊中物品的描述。
✓
author
string
制作者的名字，用于在mod列表展示。
✓
system_version
int
你始终需要对此进行定义并将其更新为当前支持的版本。如果在任何时候mod定义过程发生了巨大变化，那么您将需要更新定义以加载mod。请参阅系统版本部分以了解当前版本。
✓
contest
bool
该项目将被视为参赛项目吗？该值可以为true或false。如果未定义，则默认值为false。
✘
changelog
string
你的mod的最新更新日志。当你更新你的发布物或将其提交到创意工坊时，它将作为更改说明出现。
✘
color
string
需要十六进制颜色。这将修改mod列表中您的mod框的颜色。不定义则将默认为橙色。
✘
自定义预览
你可以在你的mod中添加一个自定义预览。
如果你想把你的mod发布到创意工坊中就必须加上。
在你的mod目录的根目录下创建它，命名为preview.png。
预览最好应遵循16：9的宽高比，并使用PNG格式。如果游戏检测到该文件，则将会自动读取该文件，因此无需执行其他任何操作！
预览的大小必须小于1 MB，才能上传到创意工坊。
Mod替换章节
注意：每个替换项现在都有自己的小节。比如贴图和声音，你就需要不同的数组。
你可以在一个mod里合并多个小节。
本指南接下来的部分会提供更多详细信息。
贴图（textures）
贴图替换数组只需要替换路径的字符串。
当前包括：
- alphamasks
- hats
- hairs
- units
- cards
贴图必须使用PNG格式并且与原图尺寸相同。
单位相关尺寸：256×256
卡图相关尺寸：256×256 和 128×128（需要两个版本。）
游戏现在会处理完整的简单路径，这意味着你不需要为特定颜色、饰品、头发等所有姿势添加路径。
例如：
“textures”: [ “units/cuties_00”, “units/cuties_01”, “cards/cuties”, ]
在游戏中，可爱者的默认颜色和颜色1的所有姿势仅被包含在2行而不是12行中。
对于卡牌，它还会自动地包含128和256贴图的变体。此处只需要ID。如果你希望添加自定义名称和卡牌台词，请参考下方的高级贴图。（注意：卡牌只需要定义一次，即使是进阶牌面。单元相关的贴图则不是这种情况。）
如果你只需要包含单个文件，而又不能享受自动填充的快感，则可以使用带特殊参数的高级贴图。如下所示。
高级贴图
高级贴图可以带有特殊参数，比如一个单元的面部坐标，或者卡牌的自定义名称和卡牌台词。
面部坐标改变单元的贴图在居中时的处理方式。最明显的例子就是游戏中的HUD。
costume_id
int
最终服装的ID。不定义此参数将默认为没有服装。
✘
custom_name
string
执行自定义卡牌名称，仅适用于卡牌路径。
✘
custom_flavor
string
执行自定义卡牌台词，仅适用于卡牌路径。
✘
single_file
bool
如果此贴图是与单元有关的单个文件，则不应自动添加所有姿势路径。可为“true”或“false”。默认为false。
✘
面部坐标必须是单位面部中心的X和Y位置。
如上所示，我的坐标是X116, Y129。
在JSON文件中，则是这个样子：
“textures”: [ { “path”: “units/alicianrone_00_05”, “face_x”: 116, “face_y”: 129 } ]
服装有它们自己的坐标。你可以通过它们的数字编号来定义服装。
查看服装部分来了解它们谁是谁。
“textures”: [ { “path”: “units/suguri_02_00_00”, “face_x”: 116, “face_y”: 129, “costume_id”: 2 } ]
这会把坐标X116 Y129添加到须玖莉夏日装扮的闲置姿态。
高级贴图可以和普通贴图一起使用。所以你可以根据需要来混合使用。
只有单元贴图和卡牌贴图能被视为高级贴图。头发、饰品等则不需要。你可以单纯地给默认颜色定义它们，并给单位颜色选项设置常规路径。
例如：
“textures”: [ { “path”: “units/sora_00_00”, “face_x”: 125, “face_y”: 140 }, { “path”: “units/sora_00_01”, “face_x”: 123, “face_y”: 138 }, { “path”: “units/sora_00_02”, “face_x”: 122, “face_y”: 145 }, { “path”: “units/sora_00_03”, “face_x”: 126, “face_y”: 141 }, { “path”: “units/sora_00_04”, “face_x”: 124, “face_y”: 170 }, { “path”: “units/sora_00_05”, “face_x”: 125, “face_y”: 137 }, “units/sora_01”, “units/sora_02”, “units/sora_03”, “units/sora_04”, “units/sora_05”, “hairs/sora_b00”, “hairs/sora_h00”, “hairs/sora_m00”, “hairs/sora_s00”, “hats/sora_00”, “hats/sora_01”, “hats/sora_02”, “hats/sora_03”, { “path”: “cards/cookie”, “custom_name”: “Sora’s cookie”, “custom_flavor”: “You’re not the only one who enjoy cookies… ―Sora” } ]
音乐
音乐替换数组需要如下几个参数。
音乐必须使用OGG格式。
unit_id
string
将修改其主题曲的单元的ID。
✓
event
string
定义一个特殊时间来触发音乐。更多信息见下文。
✓
file
string
音乐文件的路径，可以在任何文件夹。不要包含扩展名。
✓
loop_point
int
如果需要，你可以根据样本数设置循环点。它将播放整个音乐一次，然后倒回循环点。要获取所需的样本量，可以使用Audacity软件。如果未定义，它将始终从头到尾读取您的音乐。
✘
例如：
“music”: [ { “unit_id”: “sorasp”, “file”: “music/grayhued”, “loop_point”: 796411 } ]
事件
可以定义事件来影响音乐到特定位置。但是，您不能在单个条目中同时定义事件和unit_id。如果为一个事件指定了一个unit_id，则将优先考虑unit_id参数。
下面是事件表：
standby
在多人房间，或者在单人战役界面时播放。
dialog1
在对话时播放的音乐，通常在活动或者事件开始时播放。
conclusion
在对话时播放的音乐，通常在活动或者事件的尾声播放。
dialog4
在妮可和亚瑟的战役中，对话时播放的音乐。
final2
在妮可和亚瑟的战役中，对话时播放的音乐。
ending2
在职员表中播放的音乐，实际上只在你完成亚瑟和妮可的战役时使用。
idol_duet
在可爱者使用她们的Hyper时播放的音乐。
idol_instrumental
在并非可爱者或者啵噗的单元使用“特别舞台”Hyper时播放的音乐。
idol_poppo
在啵噗使用“特别舞台”Hyper时播放的音乐。
dialog5
在魅樱的战役中播放的音乐。默认的对话曲子。
dialog6
在魅樱的战役中播放的音乐。凯的登场曲。
ending3
在魅樱的战役中播放的音乐。职员表的曲子。
例如:
“music”: [ { “event”: “standby”, “file”: “music/menu”, “loop_point”: 614400 } ]
大厅的BGM就会被替换成那样。
语音
语音替换mod需要以下两个参数之一，取决于你想替换的语音类型：
- character：尝试加载替换角色语音的数组路径文件。
- system：尝试加载替换播报员语音的数组路径文件。
在从.pak加载声音文件之前，游戏将在此处列出的路径中查找文件，然后尝试加载这些文件。
例如：
“voices” : { “character”: [ “voice_cha_qp”, “voice_cha_suguri”, “voice_cha_kai” ], “system” : [ “voice_sys_suguri”, “voice_sys_kai” ] }}
如果你只想替换凯的播报员语音，就是这个样子：
“voices” : { “system” : [ “voice_sys_kai” ] }}
吊，但我要在这些文件夹里放什么？
文件夹中的文件也必须与游戏的预期相匹配。“骰子1”的声线文件的名称为“0_0.wav”（下面列出了所需的文件名），所以你想要替换的声线必须被命名为相同的名字，并且位于要替换语音的角色文件夹中。系统语音同样适用。为了得到最好的效果，请确保你的声音文件为44100HZ。
这里是一个mod的文件夹结构示例，该mod替换了QP的骰子1和4的声线，同时还有她的“100鲜橙汁”和“传送”的播报员语音：
cute qp mod (Folder name) |__ voice_cha_qp |____ 0_0.wav |____ 0_3.wav |__ voice_sys_qp |____ title.wav |____ warp.wav |__ mod.json
关于如何命名文件的信息，请查看角色语音文件名章节。
角色发色
角色发色替换数组只接受数据数组。
你有几个染发技巧可选：
- texture：依靠外部贴图来绘制头发。
- singlecolor：定义一个基础色，阴影和额外颜色来绘制头发。
- gradient：定义一个基础色，二次色，阴影和额外颜色来绘制头发。
该模块只读取以下参数：
unit_id
string
头发数据将被更改的单元ID。查看本指南的单元ID章节了解更多。
✓
hair_color
int
要改变的发色编号。从1到12。
✓
technique
string
绘制头发所使用的技术。参见上面的列表。
✓
base_color
string
十六进制颜色值。若未定义，则默认是白色。
✘
secondary_color
string
十六进制颜色值。若未定义，则默认是白色。只能在技术选“gradient”时使用。
✘
shadow_color
string
十六进制颜色值。若未定义，则默认是RGB:128,50,50。
✘
add_color
string
十六进制颜色值。若未定义，则默认不会添加颜色。
✘
你还可以为颜色指定一个alpha值：
#ff000000 : ARGB (255, 0, 0, 0)
#000000 : XRGB (0, 0, 0) (alpha永远的是255。)
Texture
贴图不需要任何特定参数。你需要按照我们的命名将贴图包含在专用模块中（参见前面的贴图章节）：
例如：
hairs/sora_00_00 :它会改变空的闲置姿态的发色1。
hairs/sora_02_00_00 :它会改变空夏日装扮的闲置姿态的发色1。
注意：即使发色文件没有出现在官方文件中，你仍然可以定义你自己的发色文件，以供游戏读取。只要文件的名称与游戏所期望的相同，就算设置好了。
JSON例子：
“hair_color”: [ { “unit_id”: “sora”, “hair_color”: 3, “technique”: “texture” } ]
Single Color
单色技术取决于你要定义来绘制头发的颜色。
JSON例子：
“hair_color”: [ { “unit_id”: “sora”, “hair_color”: 1, “technique”: “singlecolor”, “base_color”: “#000000”, “shadow_color”: “#ff0000” } ]
Gradient Color
渐变色技术取决于白色和黑色头发的纹理来绘制头发。 基本颜色是黑色部分，辅助颜色是白色部分。
JSON例子：
“hair_color”: [ { “unit_id”: “sora”, “hair_color”: 2, “technique”: “gradient”, “base_color”: “#000000”, “secondary_color”: “#ffffff”, “shadow_color”: “#ff0000” }, ]
使用渐变色或单色时使用的头发纹理如下：
以亚莉希安罗妮举例（适用于所有单元）
- hairs/alicianrone_b00_00 （基础色）
- hairs/alicianrone_h00_00（头发高光）
- hairs/alicianrone_m00_00（渐变）
- hairs/alicianrone_s00_00 （阴影）
音效
要添加自定义声音，只需在ModReplacements中创建一个名为sound_effects的条目。这是你的mod要替换的音效的列表。这些声音必须位于你的mod根目录中名为sound的文件夹中。为了获得最佳结果，请确保您的声音文件具有44100Hz的采样率。
以下是您的mod.json文件中的示例定义：
“ModReplacements”: { “sound_effects” : [ “cancel.wav”, “cardget.wav”, “decision.wav” ] }
这意味着你的mod文件夹结构应该是下面这样子：
poppo mod (文件夹名) |__ sound |____cancel.wav |____cardget.wav |____decision.wav |__ mod.json
这有什么用？ 这将这些文件替换“玩家选择了XX”，“玩家取消选择XX”和“抽卡”声音效果。本指南的末尾列出了所使用的所有音效，因此您可以在需要时将其用作参考。
===============================
参与比赛
为了参与我们的官方比赛，你需要声明一个flag
“contest”: true
在mod的定义里面，以及其他必需的参数。
这样做，你将必须发送mod文件夹中所需的所有资源。
一旦你的文件夹准备好后，就像其他mod一样，在游戏中发布。
注意：当无比赛进行时，或者时间截止，你将不能发送或者升级你的条目。
提示：因为是mod，所以你可以把你的条目当成一个mod，并让用户订阅。这样他们就可以在游戏里直接预览你的条目。
比赛开始并进行时，你的席次牌将添加到游戏中的活页夹中。
请确保包含全分辨率的艺术作品在提交文件夹中，即使mod不会读取它们。
===============================
（旧版）Mod定义
此方法已停用！
要创建你的第一个mod，你需要在“mods”文件夹中新建一个文件夹，命名为你的mod的名字。
在这个文件夹中，你需要一个mod定义文件，叫作mod.txt。内容格式如下：
< MOD_NAME > The Cuties, but Sora is alone < MOD_DESCRIPTION > This mod made Sham quite upset. < MOD_AUTHOR > Sora [Fruitbat Factory] < MOD_AUTHOR_CONTACT >
[link] < MOD_REPLACEMENTS > units/cuties_00_00 units/cuties_00_01 units/cuties_00_02 units/cuties_00_03 units/cuties_00_04 units/cuties_00_05
此语法与本地化定义文件相同。
确保文件的编码格式为UTF-8。
简要介绍一下这些值的含义：
< MOD_NAME >*
你的mod的名字。
必须与文件夹名字相同，仅被用来展示目的。
< MOD_DESCRIPTION >
你的mod的描述。
< MOD_AUTHOR_CONTACT > (可选)
你的联系方式，Steam链接，电子邮箱……
< MOD_REPLACEMENTS >*
所有你想用自定义贴图替换的文件的路径（忽略后缀名。）
*这些值必须被添加到你的mod.txt中去。如果数据遗失或损坏，则你的mod有可能无法被游戏加载。
使用此方法只能修改贴图。
===============================
(待更新）各种ID与文件名称表
