From ea8e6f20c8f841386df802627738fa4cdc975194 Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Sat, 17 Oct 2026 21:15:46 +0800 Subject: [PATCH] =?UTF-8?q?docs(10-09):=20=E5=BC=95=E5=AF=BC=E5=BC=8F?= =?UTF-8?q?=E9=87=8D=E5=86=99=20src-tour=E3=80=81code-basics?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - src-tour 以「该改哪个文件」引导，保留该不该改表、constant.ts，不含已弃用项 - code-basics 保持三段式与引导口吻，泛型比作类型的函数，保留 D-23 唯一外链 --- docs/intermediate/code-basics.md | 12 +++++++----- docs/intermediate/src-tour.md | 24 ++++++++++++++++-------- 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/intermediate/code-basics.md b/docs/intermediate/code-basics.md index a2bbd6e..88770ea 100644 --- a/docs/intermediate/code-basics.md +++ b/docs/intermediate/code-basics.md @@ -1,9 +1,11 @@ # 代码基础 -即使你只懂一点代码，也能读懂并编写本引擎的大部分内容。本篇用尽量简短的方式，补齐写中级教程所需的最小语法与类型知识。如果你已有 JavaScript / TypeScript 基础，可以快速跳过对应小节。 +你不需要成为程序员，也能读懂并改写本引擎的大部分内容：真正会用到的语法并不多。本篇用尽量简短的方式，补齐写中级教程所需的最小语法与类型知识——即使你只懂一点代码，也能跟着走完。已有 JavaScript / TypeScript 基础的话，可以快速跳过对应小节。 ## 一、简明语法 +先认识四种最常见的写法：变量、函数、分支与循环、对象与数组。会用它们，就能表达大多数「让游戏做点什么」的需求。 + ### 变量 ```ts @@ -56,7 +58,7 @@ hero.atk = hero.atk + 5; ## 二、模块与引入 -一个文件就是一个模块。用 `export` 把内容暴露出去，用 `import` 从别的模块引入。在本引擎里，文件顶部的 `import` 必须紧挨在一起，中间不夹注释或空行。 +当代码变多，就要拆成多个文件。一个文件就是一个模块：用 `export` 把内容暴露出去，用 `import` 从别的模块引入。在本引擎里，文件顶部的 `import` 必须紧挨在一起，中间不夹注释或空行。 ```ts // math.ts @@ -68,7 +70,7 @@ export const PI = 3.14; ``` ```ts -// main.ts +// app.ts import { add, PI } from './math'; add(1, PI); @@ -84,7 +86,7 @@ math.add(1, 2); ## 三、类型入门 -TypeScript 在 JavaScript 之上增加了类型，用来描述「这份数据长什么样」。类型会在编写与编译阶段被检查，帮助你在运行之前就发现错误。 +TypeScript 在 JavaScript 之上增加了类型，用来描述「这份数据长什么样」。类型会在编写与编译阶段被检查，帮你在运行之前就发现错误。 ### 基础类型 @@ -109,7 +111,7 @@ const hero: Hero = { hp: 100, atk: 10 }; ### 泛型：类型的「函数」 -普通函数接收**值**、返回**值**；泛型则接收**类型**、返回**类型**，可以把它理解成「类型的函数」。尖括号里的 `T` 是一个类型参数，调用时才确定具体是什么类型。 +如果觉得「类型」本身有点抽象，可以这样理解泛型：普通函数接收**值**、返回**值**；泛型则接收**类型**、返回**类型**，相当于一个「类型的函数」。尖括号里的 `T` 是一个类型参数，调用时才确定具体是什么类型。 ```ts // T 是类型参数，取什么类型由调用时传入的值决定 diff --git a/docs/intermediate/src-tour.md b/docs/intermediate/src-tour.md index 0d88cb7..69594b5 100644 --- a/docs/intermediate/src-tour.md +++ b/docs/intermediate/src-tour.md @@ -1,31 +1,35 @@ # src 导览 -`src` 是游戏的入口代码，也是中级教程涉及最多的地方。本篇带你认识它的主要目录，并说明哪些地方通常需要改、哪些通常不用动。两端的分工见 [数据端与渲染端](./data-vs-render.md)。 +想在游戏里加点自己的东西，第一件事往往是：我该改哪个文件？游戏的入口代码都在 `src` 下，而中级教程绝大多数时候只会碰到其中几个目录。本篇带你走一遍 `src`——先弄清每个目录在做什么，最后用一张表回答「它到底该不该改」。 + +如果还不清楚数据端与渲染端的分工，先看一眼[数据端与渲染端](./data-vs-render.md)。 ## src/data：数据端 -数据端代码。游戏的逻辑与结果都在这里定义，是本教程后续的重点。常见子目录： +凡是「游戏世界里发生了什么」——勇士剩多少血、怪物怎么被打、地图如何读取——都由 `src/data` 里的代码决定。它是本教程后续的重点，常见子目录： - `src/data/enemy/`：怪物相关逻辑，如特殊属性（`special.ts`）、光环（`aura.ts`）、伤害计算（`calculator.ts`）等； - `src/data/event/`：地图事件的内建函数； - `src/data/hero/`：勇士移动、通行性等实现； -- `src/data/hook/`：数据端内置钩子的实现与注册（见 [钩子](./hooks.md)）； +- `src/data/hook/`：数据端内置钩子的实现与注册（见[钩子](./hooks.md)）； - `src/data/loader/`、`src/data/plugin/`、`src/data/replay/`：加载、数据端插件、录像指令等。 -数据端的入口是 `entry.ts`，它负责装配并创建数据端主对象 `state`；`initialize.ts` 中的 `MainDataPlugin` 则承担主要的初始化工作。 +数据端的入口是 `entry.ts`，它负责装配并创建数据端主对象 `state`；`initialize.ts` 中的 `MainDataPlugin` 则承担主要的初始化工作。你通常不需要改这两个文件，但值得知道「一切是从这里搭起来的」。 ## src/client：渲染端 -渲染端代码，负责画面与交互。其构成与数据端一一对应： +凡是「玩家看到什么、点了什么」——画面、动画、界面——都由 `src/client` 负责。它的构成与数据端一一对应： - `src/client/entry.ts`：渲染端入口，创建渲染端主对象； - `src/client/initialize.ts`：渲染端主插件； - `src/client/plugin/`：渲染端插件； - `src/client/ui/`：界面相关代码。 +两侧如何分工、各自负责什么，见[数据端与渲染端](./data-vs-render.md)。 + ## src/content：内容层 -游戏内容数据，与代码逻辑分开存放，大多以 `.jsonc` 形式存在： +游戏内容与代码逻辑分开存放，大多以 `.jsonc` 形式存在。想调数值、换贴图、改地图，就来这里找： - `core.jsonc`：核心配置，如勇士初始属性与初始位置； - `enemy.jsonc`、`item.jsonc`、`tile.jsonc`：怪物、道具、图块定义； @@ -34,10 +38,12 @@ ## src/constant.ts：常量 -游戏的底层核心常量，例如数据端核心配置 `CORE_URL`、勇士默认朝向组 `HERO_FACE`、渲染画布 `RENDER_CANVAS`、渲染宽高 `RENDER_WIDTH` 与 `RENDER_HEIGHT` 等。文件内已注明「不懂的话千万不要动」，一般不需要修改。 +游戏的底层核心常量都集中在这个文件，例如数据端核心配置 `CORE_URL`、勇士默认朝向组 `HERO_FACE`、渲染画布 `RENDER_CANVAS`、渲染宽高 `RENDER_WIDTH` 与 `RENDER_HEIGHT` 等。文件里已注明「不懂的话千万不要动」，一般不需要修改。 ## 其余文件（通常不用改） +下面这些文件各有职责，但绝大多数需求都碰不到它们，知道它们在哪、干什么就够了： + - `src/data.ts`：数据端入口，仅在录像验证时运行； - `src/bootstrap.ts`：启动入口，创建渲染端主对象并打开加载界面； - `src/package.json`：入口包的依赖声明； @@ -45,6 +51,8 @@ ## 该不该改 +把上面几节收成一张表，动手前对照一下： + | 路径 | 用途 | 是否通常需要改动 | | --- | --- | --- | | `src/data/` | 数据端逻辑与结果 | 是，本教程重点 | @@ -56,4 +64,4 @@ | `src/package.json` | 入口包依赖声明 | 否，一般不动 | | `src/styles.less` | 全局样式 | 否，一般不动 | -想先补齐读写这些文件所需的语法与类型知识，见 [代码基础](./code-basics.md)。 +想先补齐读写这些文件所需的语法与类型知识，见[代码基础](./code-basics.md)。