项目结构

一个 Kiny 项目就是一个文件夹。里面长这样：

雾港之夜/
├── 雾港之夜.kiw        作品清单（必需）
├── main.kin           入口故事文件（必需，名字可改）
├── chapters/          故事文件想怎么分就怎么分
│   ├── 港口.kin
│   └── 结局.kin
├── theme.css          作品外观（新建项目自带）
├── characters.json    可选：角色表，声明后台词按说话人着色
└── assets/            可选：图、音、字体
    ├── 港口.webp
    ├── 潮声.mp3
    └── 楷体.woff2

除了前两项，其余都是可选的；文件夹怎么起名、怎么分层，引擎完全不关心。

作品清单 .kiw

编辑器新建项目时会生成一个 <作品名>.kiw，内容是一小段 JSON：

{
  "name": "雾港之夜",
  "version": "1.0.0",
  "engine": "0.14.0",
  "entry": "main.kin"
}

平时不用手动改这个文件：作品名、版本这些在编辑器的**文件 → 项目设置…**里改。

老项目的清单文件叫 kiny.json，现在仍然认。不过编辑器打开旧项目时会顺手把它改名成 <作品名>.kiw——如果你在版本控制或备份脚本里盯着 kiny.json 这个名字，留意一下。新建的项目一律是 .kiw。

变量不在这里声明。 清单只放作品元数据；故事里的变量全部写在 .kin 里（见后面的「变量、条件与逻辑」一篇）。

故事文件怎么分

引擎会自动扫描项目里所有 .kin 文件，不需要任何「引入」「包含」声明——你新建一个 .kin 文件，写进去的节点立刻就能被跳转到。

因此有两条要点：

• 节点名在整个项目里必须唯一，跨文件也算。两个文件里都有 === 开场 === 会报错。
• 文件夹只是给你自己看的。chapters/港口.kin 和根目录下的 港口.kin 对引擎没有区别，跳转时也不写文件名——只写节点名。

所以分文件的标准是「你翻起来方便」：一章一个文件、一条支线一个文件、或者干脆全写在 main.kin 里，都行。

开场：故事从哪一行开始

入口文件里、第一个 === 节点 === 之前的那一整段叫开场。故事从这里开始播放。

~ let gold = 10
你摸了摸口袋，还有 {gold} 枚硬币。
-> 码头

=== 码头 ===
潮水正在退去。
-> END

开场里可以写正文、可以声明变量、可以下命令，按写下的顺序执行。

开场执行到底如果没有跳转，故事就结束了。 这是新手最容易踩的一脚：

~ let gold = 10        ← 开场只有这一行

=== 码头 ===           ← 永远到不了这里
潮水正在退去。
-> END

上面这段跑起来是一片空白加「故事结束」——开场执行完那行声明就到底了，而 === 码头 === 不会被自动进入。加一行 -> 码头 就好了。

开场没有名字，你没法 -> 到它，只能从它跳出去。

如果整个入口文件里一个节点都没有，那它整个就是一段开场——一篇纯文本也是合法的作品。

图片、音频、字体放哪

assets/ 只是个习惯，不是规定。 图和音靠命令引用，路径相对项目根：

@bg_show("assets/港口.webp")
@bgm_play("assets/潮声.mp3")
雾散了，港口露出轮廓。
@img("assets/信件.webp", "一封被水浸过的信")
你从怀里摸出那封信。

@bg_show 铺全屏背景、@img 在正文流里插一张图、@bgm_play 放背景音乐——三条命令的用途各不相同。完整的命令清单与用法见后面的「演出命令」一篇。

字体和 CSS 不一样——它们会被自动加载：

• 项目里任意位置的 .css 都会自动生效，按路径字典序依次应用。想控制先后就用 10- / 20- 这样的文件名前缀；不想让某个文件生效，把扩展名改掉（如 theme.css.bak）。
• 字体文件（.woff2 / .woff / .ttf / .otf）会自动注册，族名 = 文件名去掉扩展名。把 楷体.woff2 丢进项目，正文里直接 <font=楷体> 就能用，不必写 @font-face。

以 . 开头的文件夹和 node_modules 会被跳过。

只有 .css 与字体自动加载。 .js / .json / .txt 等文件可以放在项目里、也能在编辑器里编辑，但不参与自动加载——尤其 .js 不会被执行。

作品外观

新建项目自带一个 theme.css，改它就换掉整个阅读页的外观：底色、正文字体、字号、行高、阅读栏宽都在里面。编辑器里点开它是一个可视化编辑器，拖着调就行；想手写 CSS 就切到「原文」页。

完整的外观定制（内置主题、自带字体、作品自己的样式表）见后面的「作品外观」一篇。

角色表

项目根放一份 characters.json 声明角色之后，正文里在台词行开头标出说话人，阅读时该行就按角色着色：

<克里斯托弗> 我今天出门了。
阿黎娅：外面在下雨。

写法与配色见后面的「角色与台词着色」一篇。

接下来

项目的骨架就这些。下一篇讲正文写作——分段、标点、加粗变色、句中停顿。