@ccgf/game-template 0.2.25 → 0.2.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,11 @@
1
+ (function () {
2
+ var page = (location.pathname.split('/').pop() || 'index.html').toLowerCase();
3
+ var links = Array.prototype.slice.call(document.querySelectorAll('.page-link'));
4
+
5
+ links.forEach(function (link) {
6
+ var href = (link.getAttribute('href') || '').split('/').pop().toLowerCase();
7
+ if (href === page) {
8
+ link.classList.add('active');
9
+ }
10
+ });
11
+ })();
@@ -0,0 +1,125 @@
1
+ <!DOCTYPE html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>数据与流程 · CCGF 使用文档</title>
7
+ <link rel="stylesheet" href="./style.css">
8
+ </head>
9
+ <body>
10
+ <aside class="sidebar">
11
+ <div class="brand"><strong>CCGF</strong><span>使用文档</span></div>
12
+ <nav>
13
+ <a href="./index.html" class="page-link">首页 / 快速开始</a>
14
+ <a href="./framework.html" class="page-link">框架核心</a>
15
+ <a href="./data.html" class="page-link">数据与流程</a>
16
+ <a href="./shared.html" class="page-link">公共模块</a>
17
+ <a href="./tools.html" class="page-link">工具与 FAQ</a>
18
+ </nav>
19
+ <div class="version">数据表 · Loading · 子游戏</div>
20
+ </aside>
21
+
22
+ <main>
23
+ <header class="page-header">
24
+ <p class="breadcrumb">CCGF 使用文档 / 数据与流程</p>
25
+ <h1>数据与流程</h1>
26
+ <p>CSV 数据表、TableManager、Loading 和子游戏场景切换。</p>
27
+ </header>
28
+
29
+ <section id="table">
30
+ <h2>数据表</h2>
31
+ <p>CSV 源放在工程根 <code>tables/</code>,目录精确镜像 <code>assets/</code>;导表工具导出 <code>.bin</code>。前三行固定为:类型、字段名、注释;第一列必须是 <code>ID:int</code>。</p>
32
+ <pre><code>int,string,float,int[]
33
+ ID,name,attack,levels
34
+ 道具ID,名称,攻击,等级
35
+ 1001,木剑,10,1#2#3
36
+ </code></pre>
37
+ <p>导出后:</p>
38
+ <pre><code>tables/resources/tables/Weapon_武器表.csv
39
+ -> assets/resources/tables/Weapon.bin
40
+ </code></pre>
41
+ <pre><code>import { TableManager } from '@ccgf/framework';
42
+
43
+ interface IWeaponRow {
44
+ ID: number;
45
+ name: string | null;
46
+ attack: number | null;
47
+ levels: number[] | null;
48
+ }
49
+
50
+ const table = await TableManager.load&lt;IWeaponRow&gt;('tables/Weapon');
51
+ const row = table.get(1001);
52
+ console.log(row?.name);
53
+ </code></pre>
54
+ <p>子包表需要先加载 bundle:<code>TableManager.load('tables/Item', 'candy')</code>。</p>
55
+ <h3>表规则</h3>
56
+ <ul>
57
+ <li><code>int / float / string / bool</code> 及一维/二维数组</li>
58
+ <li>空单元格 = <code>null</code>;ID 为空整行跳过</li>
59
+ <li>数组元素用 <code>#</code>,二维行用 <code>|</code></li>
60
+ <li>表名取文件名最后一个 <code>_</code> 之前的部分</li>
61
+ </ul>
62
+ </section>
63
+
64
+ <section id="loading">
65
+ <h2>Loading</h2>
66
+ <p>Loading 是常驻 UI,不经过 ViewManager。AppStart 上指定 <code>loadingPrefab</code>,面板根节点实现 <code>onShow/onProgress/onHide</code> 即可。</p>
67
+ <pre><code>import { Component, Label, ProgressBar, tween, UIOpacity } from 'cc';
68
+ import type { ILoadingHandler } from '@ccgf/framework';
69
+
70
+ export class LoadingPanel extends Component implements ILoadingHandler {
71
+ public bar: ProgressBar | null = null;
72
+ public label: Label | null = null;
73
+
74
+ public onProgress(progress: number, label?: string): void {
75
+ if (this.bar) this.bar.progress = progress;
76
+ if (this.label && label) this.label.string = label;
77
+ }
78
+
79
+ public async onHide(): Promise&lt;void&gt; {
80
+ const opacity = this.node.getComponent(UIOpacity) ?? this.node.addComponent(UIOpacity);
81
+ await new Promise&lt;void&gt;((resolve) => {
82
+ tween(opacity).to(0.25, { opacity: 0 }).call(resolve).start();
83
+ });
84
+ }
85
+ }
86
+ </code></pre>
87
+ <p>业务切换默认带 Loading;不需要时传 <code>{ loading: false }</code>。也可以手动包自定义步骤:</p>
88
+ <pre><code>import { LoadingService } from '@ccgf/framework';
89
+
90
+ await LoadingService.run(async (progress) => {
91
+ progress(0.1, '检查更新');
92
+ await checkUpdate(progress);
93
+ progress(1, '完成');
94
+ }, 1000);
95
+ </code></pre>
96
+ </section>
97
+
98
+ <section id="subgame">
99
+ <h2>子游戏 / 切场景</h2>
100
+ <pre><code>import { SubGame } from '@ccgf/framework';
101
+
102
+ // 加载子包 + 切场景 + 启动子包模块,默认带 Loading
103
+ await SubGame.enter('candy', 'candy');
104
+
105
+ // 返回 homeScene,默认带 Loading
106
+ await SubGame.exit('candy');
107
+
108
+ // 不需要 Loading
109
+ await SubGame.enter('candy', 'candy', { loading: false });
110
+ await SubGame.exit('candy', { loading: false });
111
+ </code></pre>
112
+ <p><code>exit</code> 先拆子包 View/模块,切回主场景,最后释放 bundle。主场景模块只重跑 <code>onSceneEnter</code>,不重启 <code>start</code>。</p>
113
+ <h3>子包目录</h3>
114
+ <pre><code>assets/bundles/candy/
115
+ scene/candy.scene
116
+ scripts/candymain/
117
+ views/candymain/
118
+ </code></pre>
119
+ </section>
120
+
121
+ <footer><p>CCGF 本地文档 · 数据与流程</p></footer>
122
+ </main>
123
+ <script src="./app.js"></script>
124
+ </body>
125
+ </html>
@@ -0,0 +1,197 @@
1
+ <!DOCTYPE html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>框架核心 · CCGF 使用文档</title>
7
+ <link rel="stylesheet" href="./style.css">
8
+ </head>
9
+ <body>
10
+ <aside class="sidebar">
11
+ <div class="brand"><strong>CCGF</strong><span>使用文档</span></div>
12
+ <nav>
13
+ <a href="./index.html" class="page-link">首页 / 快速开始</a>
14
+ <a href="./framework.html" class="page-link">框架核心</a>
15
+ <a href="./data.html" class="page-link">数据与流程</a>
16
+ <a href="./shared.html" class="page-link">公共模块</a>
17
+ <a href="./tools.html" class="page-link">工具与 FAQ</a>
18
+ </nav>
19
+ <div class="version">framework 0.1.14</div>
20
+ </aside>
21
+
22
+ <main>
23
+ <header class="page-header">
24
+ <p class="breadcrumb">CCGF 使用文档 / 框架核心</p>
25
+ <h1>框架核心</h1>
26
+ <p>工程结构、启动、模块、界面、事件、存档和调试。</p>
27
+ </header>
28
+
29
+ <section id="layout">
30
+ <h2>工程结构</h2>
31
+ <pre><code>assets/
32
+ scenes/
33
+ boot.scene # 唯一启动场景
34
+ main.scene # 主场景
35
+ scripts/
36
+ framework/ # 开发工作区才有;普通工程走 npm
37
+ gameplay/ # 项目业务模块
38
+ shared/ # 公共模块源码(开发工作区)
39
+ resources/
40
+ tables/ # 导出的 .bin 数据表
41
+ views/ # View 预制体
42
+ bundles/ # 子包(可选)
43
+ tables/ # CSV 编辑源,镜像 assets/
44
+ extensions/ # 编辑器扩展
45
+ docs/guide/ # 本使用文档
46
+ </code></pre>
47
+ <p>开发工作区用相对路径引用框架;普通工程从 <code>@ccgf/framework</code> npm 包引用,扩展创建代码时会自动选择。</p>
48
+ </section>
49
+
50
+ <section id="boot">
51
+ <h2>启动与 Boot</h2>
52
+ <p><code>AppStart</code> 只放在 <code>boot.scene</code>,节点设为常驻。主场景和子游戏场景都不应再放 AppStart。</p>
53
+ <table>
54
+ <thead><tr><th>属性</th><th>说明</th></tr></thead>
55
+ <tbody>
56
+ <tr><td><code>homeScene</code></td><td>主场景名,默认 <code>main</code>;退出子游戏会回到这里</td></tr>
57
+ <tr><td><code>loadingPrefab</code></td><td>加载面板预制体;留空则不显示面板</td></tr>
58
+ <tr><td><code>loadingMinShowMs</code></td><td>Loading 最短展示时间,默认 1000ms</td></tr>
59
+ <tr><td><code>enableGm</code></td><td>是否启用 F7 GM</td></tr>
60
+ </tbody>
61
+ </table>
62
+ <h3>启动顺序</h3>
63
+ <ol>
64
+ <li>AppStart.onLoad:常驻节点、<code>GameIns.init</code></li>
65
+ <li>AppStart.start:设置 homeScene,等 Loading 加载主场景</li>
66
+ <li>主场景 <code>onSceneEnter</code>:模块重新显示场景 View</li>
67
+ <li>加载结束:<code>Gm.open()</code></li>
68
+ </ol>
69
+ </section>
70
+
71
+ <section id="module">
72
+ <h2>Module / Model</h2>
73
+ <p>Module 是业务控制器,Model 是数据。Module 的 <code>start</code> 只执行一次,切场景只触发 <code>onSceneEnter/onSceneExit</code>。</p>
74
+ <pre><code>import { Model, Persistent } from '@ccgf/framework';
75
+
76
+ export class PlayerModel extends Model {
77
+ @Persistent
78
+ public level = 1;
79
+
80
+ public levelUp(): void {
81
+ this.level++;
82
+ this.changed('level');
83
+ }
84
+ }
85
+ </code></pre>
86
+ <pre><code>import { Module, RegisterModule } from '@ccgf/framework';
87
+ import { PlayerModel } from './PlayerModel';
88
+
89
+ @RegisterModule({
90
+ order: 1,
91
+ model: PlayerModel,
92
+ })
93
+ export class PlayerModule extends Module&lt;PlayerModel&gt; {
94
+ public override start(): void {
95
+ // 只跑一次:加载数据、注册服务
96
+ }
97
+
98
+ public override onSceneEnter(sceneName: string): void {
99
+ // 每次进入场景:show / 刷新 UI
100
+ }
101
+
102
+ public override onSceneExit(sceneName: string): void {
103
+ // 离开场景:清理场景级状态
104
+ }
105
+ }
106
+ </code></pre>
107
+ <p>模块注册靠装饰器,脚本必须被执行。放在 <code>assets/scripts</code> 下的脚本会随工程打包执行;从 npm 安装的模块需要显式 import。</p>
108
+ </section>
109
+
110
+ <section id="view">
111
+ <h2>View / UI</h2>
112
+ <p>View 是场景级界面,切场景会随旧场景销毁。View 预制体放在 <code>assets/resources/views/&lt;module&gt;/</code>,脚本放在 <code>assets/scripts/gameplay/&lt;module&gt;/views/</code>。</p>
113
+ <pre><code>import { View, RegisterView, ELayer } from '@ccgf/framework';
114
+
115
+ @RegisterView({
116
+ name: 'BagView',
117
+ path: 'views/bag/BagView',
118
+ layer: ELayer.Window,
119
+ })
120
+ export class BagView extends View {
121
+ protected onShow(...args: unknown[]): void {
122
+ // 界面显示
123
+ }
124
+
125
+ protected onHide(): void {
126
+ super.onHide();
127
+ }
128
+ }
129
+ </code></pre>
130
+ <pre><code>import { ViewManager } from '@ccgf/framework';
131
+ import { BagView } from './views/BagView';
132
+
133
+ await ViewManager.getInstance().show(BagView);
134
+ </code></pre>
135
+ <p>层级:<code>Scene / Window / Popup / Guide / Tips</code>。ViewManager 在场景切换后重建 layer;普通 View 不会跨场景保留。</p>
136
+ </section>
137
+
138
+ <section id="event">
139
+ <h2>事件</h2>
140
+ <p>跨模块通信用全局 <code>eventBus</code>。事件名格式建议 <code>domain:action</code>。</p>
141
+ <pre><code>// PlayerEvents.ts
142
+ declare global {
143
+ interface IGameEvents {
144
+ 'player:levelup': { level: number };
145
+ }
146
+ }
147
+ export {};
148
+ </code></pre>
149
+ <pre><code>import { eventBus } from '@ccgf/framework';
150
+
151
+ eventBus.emit('player:levelup', { level: 2 });
152
+
153
+ eventBus.on('player:levelup', ({ level }) => {
154
+ console.log(level);
155
+ }, this);
156
+ </code></pre>
157
+ <p>订阅了就要在隐藏/销毁时退订;用 <code>target</code> 注册后可以 <code>eventBus.targetOff(this)</code> 一次清理。</p>
158
+ </section>
159
+
160
+ <section id="save">
161
+ <h2>存档</h2>
162
+ <p>Model 字段标 <code>@Persistent</code> 才会落盘。启动时框架自动恢复,业务只需要等 <code>GameIns.ready</code>。</p>
163
+ <pre><code>import { Model, Persistent } from '@ccgf/framework';
164
+
165
+ export class SettingsModel extends Model {
166
+ public static readonly saveKey = 'settings'; // 改类名也不丢老档
167
+
168
+ @Persistent
169
+ public sound = true;
170
+
171
+ public setSound(on: boolean): void {
172
+ this.sound = on;
173
+ this.changed('sound');
174
+ void this.save();
175
+ }
176
+ }
177
+ </code></pre>
178
+ <p><code>changed()</code> 只通知界面;<code>save()</code> 才真正写盘。高频进度建议标脏后批量保存,完成/领取等关键节点立即保存。</p>
179
+ </section>
180
+
181
+ <section id="gm">
182
+ <h2>GM 调试</h2>
183
+ <p>Boot 的 AppStart 勾选 <code>enableGm</code> 后,运行时按 F7 打开 GM。命令用 <code>Gm.register</code> 注册:</p>
184
+ <pre><code>import { Gm } from '@ccgf/framework';
185
+
186
+ Gm.register((paramStr: string) => {
187
+ const count = Number(paramStr) || 1;
188
+ console.log('add item', count);
189
+ }, 'bag.add', 'bag');
190
+ </code></pre>
191
+ </section>
192
+
193
+ <footer><p>CCGF 本地文档 · 框架核心</p></footer>
194
+ </main>
195
+ <script src="./app.js"></script>
196
+ </body>
197
+ </html>
@@ -0,0 +1,74 @@
1
+ <!DOCTYPE html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>CCGF 使用文档</title>
7
+ <link rel="stylesheet" href="./style.css">
8
+ </head>
9
+ <body>
10
+ <aside class="sidebar">
11
+ <div class="brand">
12
+ <strong>CCGF</strong>
13
+ <span>使用文档</span>
14
+ </div>
15
+ <nav>
16
+ <a href="./index.html" class="page-link">首页 / 快速开始</a>
17
+ <a href="./framework.html" class="page-link">框架核心</a>
18
+ <a href="./data.html" class="page-link">数据与流程</a>
19
+ <a href="./shared.html" class="page-link">公共模块</a>
20
+ <a href="./tools.html" class="page-link">工具与 FAQ</a>
21
+ </nav>
22
+ <div class="version">framework 0.1.14 · 文档随模板生成</div>
23
+ </aside>
24
+
25
+ <main>
26
+ <header class="hero">
27
+ <h1>CCGF 使用文档</h1>
28
+ <p>从 Boot 启动、模块/界面、存档、数据表,到 Loading、子游戏和地图算法。</p>
29
+ <p class="note">本页是本地文档,不依赖网络。示例代码可以直接复制到工程里修改。</p>
30
+ </header>
31
+
32
+ <section>
33
+ <h2>按主题查看</h2>
34
+ <div class="page-grid">
35
+ <a class="page-card" href="./framework.html">
36
+ <h3>框架核心</h3>
37
+ <p>工程结构、Boot、Module/Model、View、事件、存档、GM。</p>
38
+ </a>
39
+ <a class="page-card" href="./data.html">
40
+ <h3>数据与流程</h3>
41
+ <p>CSV 数据表、TableManager、Loading、子游戏切换。</p>
42
+ </a>
43
+ <a class="page-card" href="./shared.html">
44
+ <h3>公共模块</h3>
45
+ <p>red-dot、guide、flow-field、tilemap、pathfinding。</p>
46
+ </a>
47
+ <a class="page-card" href="./tools.html">
48
+ <h3>工具与 FAQ</h3>
49
+ <p>扩展工作台、创建目录约定、常见问题。</p>
50
+ </a>
51
+ </div>
52
+ </section>
53
+
54
+ <section>
55
+ <h2>快速开始</h2>
56
+ <h3>1. 打开工程</h3>
57
+ <p>使用 Cocos Creator 3.8.8 打开工程根目录。扩展会自动安装到 <code>extensions/</code>,首次打开可能需要刷新资源库。</p>
58
+ <h3>2. 设置启动场景</h3>
59
+ <p>构建/预览的启动场景设置为 <code>assets/scenes/boot.scene</code>。Boot 只负责初始化框架和加载主场景。</p>
60
+ <h3>3. 等框架就绪</h3>
61
+ <pre><code>import { GameIns } from '@ccgf/framework';
62
+
63
+ await GameIns.ready; // 存档 + 管理器初始化完成
64
+ </code></pre>
65
+ <p>正式流程建议在 Loading 结束、进入主界面前等待 <code>GameIns.ready</code>。</p>
66
+ </section>
67
+
68
+ <footer>
69
+ <p>CCGF 本地文档 · 生成于工程模板 · 如需更新,修改 <code>docs/guide/</code> 后重新打包模板。</p>
70
+ </footer>
71
+ </main>
72
+ <script src="./app.js"></script>
73
+ </body>
74
+ </html>
@@ -0,0 +1,161 @@
1
+ <!DOCTYPE html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>公共模块 · CCGF 使用文档</title>
7
+ <link rel="stylesheet" href="./style.css">
8
+ </head>
9
+ <body>
10
+ <aside class="sidebar">
11
+ <div class="brand"><strong>CCGF</strong><span>使用文档</span></div>
12
+ <nav>
13
+ <a href="./index.html" class="page-link">首页 / 快速开始</a>
14
+ <a href="./framework.html" class="page-link">框架核心</a>
15
+ <a href="./data.html" class="page-link">数据与流程</a>
16
+ <a href="./shared.html" class="page-link">公共模块</a>
17
+ <a href="./tools.html" class="page-link">工具与 FAQ</a>
18
+ </nav>
19
+ <div class="version">npm 按需安装 · 业务直接 import</div>
20
+ </aside>
21
+
22
+ <main>
23
+ <header class="page-header">
24
+ <p class="breadcrumb">CCGF 使用文档 / 公共模块</p>
25
+ <h1>公共模块</h1>
26
+ <p>扩展「公共模块」页安装 <code>@ccgf/*</code> 包,业务直接 import 包名。</p>
27
+ </header>
28
+
29
+ <section id="install">
30
+ <h2>安装与使用</h2>
31
+ <p>在扩展「公共模块」页搜索并安装;或手动:</p>
32
+ <pre><code>npm i @ccgf/tilemap @ccgf/pathfinding
33
+ </code></pre>
34
+ <p>公共模块不依赖工程源码,升级通过 npm;<strong>不要修改 node_modules</strong>。需要项目侧资源(如红点默认 prefab)的模块,由扩展在安装时生成。</p>
35
+ </section>
36
+
37
+ <section id="red-dot">
38
+ <h2>红点 @ccgf/red-dot</h2>
39
+ <p>路径就是 id,父子节点自动聚合;“已读”跟着存档走。</p>
40
+ <pre><code>import '@ccgf/red-dot';
41
+ import { Reddot, EReddotAlign } from '@ccgf/red-dot';
42
+
43
+ // 业务:这一条有新东西
44
+ Reddot.trigger('bag.tabs.0.item.1001');
45
+
46
+ // UI:挂到节点 / 标记已读
47
+ Reddot.bind('bag.tabs.0.item.1001', itemNode, EReddotAlign.RIGHT_TOP);
48
+ Reddot.markRead('bag.tabs.0.item.1001');
49
+ </code></pre>
50
+ </section>
51
+
52
+ <section id="guide">
53
+ <h2>新手引导 @ccgf/guide</h2>
54
+ <pre><code>import { GuideBase, GuideChain, RegisterGuide, GuideSystem } from '@ccgf/guide';
55
+
56
+ @RegisterGuide('newbie')
57
+ export class NewbieGuide extends GuideBase {
58
+ protected build(chain: GuideChain): void {
59
+ chain.focusOn(() => this.view(HudView)?.bagButton)
60
+ .condition(() => this.view(BagView)?.isShow() === true, 15);
61
+ }
62
+ }
63
+
64
+ GuideSystem.tryStart('newbie');
65
+ </code></pre>
66
+ <p>引导需要遮罩资源时由扩展在安装模块时生成;运行前 import 一次模块入口。</p>
67
+ </section>
68
+
69
+ <section id="flow-field">
70
+ <h2>流场寻路 @ccgf/flow-field</h2>
71
+ <pre><code>import { Grid } from '@ccgf/pathfinding';
72
+ import { FlowField } from '@ccgf/flow-field';
73
+
74
+ const grid = Grid.fromText([
75
+ '.....',
76
+ '.###.',
77
+ '.....',
78
+ ]);
79
+ const field = new FlowField(grid, [{ x: 4, y: 1 }]);
80
+ const next = field.nextStepAt(0, 1);
81
+ </code></pre>
82
+ <p>多个单位冲同一组目标用流场;每个单位目标不同且数量少时用 A*。</p>
83
+ </section>
84
+
85
+ <section id="tilemap">
86
+ <h2>地图拓扑 @ccgf/tilemap</h2>
87
+ <p>只计算拓扑/坐标,不判断可走性、不创建节点、不做渲染。</p>
88
+
89
+ <h3>方格</h3>
90
+ <pre><code>import { SquareGrid } from '@ccgf/tilemap';
91
+
92
+ const grid = new SquareGrid(20, 20);
93
+ const index = grid.index(5, 5);
94
+ const neighbors4 = grid.neighbors(index);
95
+ const neighbors8 = grid.neighbors(index, [], true);
96
+ const area = grid.range(index, 2);
97
+ const line = grid.line(grid.index(0, 0), grid.index(10, 10));
98
+ </code></pre>
99
+
100
+ <h3>真等距</h3>
101
+ <pre><code>import { IsoProjection } from '@ccgf/tilemap';
102
+
103
+ const iso = new IsoProjection({ tileWidth: 64, tileHeight: 32 });
104
+ const world = iso.toWorld(3, 5); // 格子中心
105
+ const cell = iso.pick(world.x, world.y);
106
+ const depth = iso.sortKey(3, 5); // 升序 = 先画后面
107
+ </code></pre>
108
+
109
+ <h3>六边形</h3>
110
+ <pre><code>import { HexGrid } from '@ccgf/tilemap';
111
+
112
+ const hex = new HexGrid({
113
+ cols: 20,
114
+ rows: 20,
115
+ size: 32,
116
+ orientation: 'flat',
117
+ offset: 'odd-q',
118
+ });
119
+
120
+ const i = hex.index(5, 5);
121
+ const neighbors = hex.neighbors(i);
122
+ const ring = hex.ring(i, 2);
123
+ const point = hex.toWorld(i);
124
+ const picked = hex.fromWorld(point.x, point.y);
125
+ </code></pre>
126
+ <p>坐标约定:左下原点,x 右、y 上;第 0 行是最下面一行。</p>
127
+ </section>
128
+
129
+ <section id="pathfinding">
130
+ <h2>寻路 @ccgf/pathfinding</h2>
131
+ <h3>A*(自带网格)</h3>
132
+ <pre><code>import { Grid, findPath } from '@ccgf/pathfinding';
133
+
134
+ const grid = Grid.fromText([
135
+ '.....',
136
+ '.###.',
137
+ '.....',
138
+ ]);
139
+
140
+ const result = findPath(grid, { x: 0, y: 1 }, { x: 4, y: 1 });
141
+ if (result.found) {
142
+ console.log(result.path);
143
+ }
144
+ </code></pre>
145
+
146
+ <h3>自定义图 / 六边形</h3>
147
+ <pre><code>import { HexGrid } from '@ccgf/tilemap';
148
+ import { findPathOnGraph } from '@ccgf/pathfinding';
149
+
150
+ const hex = new HexGrid({ cols: 20, rows: 20, size: 32 });
151
+ const result = findPathOnGraph(hex, hex.index(0, 0), hex.index(10, 8));
152
+ </code></pre>
153
+ <p>带阻挡的自定义图,给 <code>findPathOnGraph</code> 传 <code>neighbors / contains / isBlocked / heuristic</code> 即可。</p>
154
+ <p class="note">地图产品层(MapData / 关卡包 / 渲染 / 编辑器)还未实现,见工程里的地图 TODO。</p>
155
+ </section>
156
+
157
+ <footer><p>CCGF 本地文档 · 公共模块</p></footer>
158
+ </main>
159
+ <script src="./app.js"></script>
160
+ </body>
161
+ </html>
@@ -0,0 +1,246 @@
1
+ :root {
2
+ --bg: #f5f6f8;
3
+ --panel: #ffffff;
4
+ --text: #22242a;
5
+ --muted: #666b76;
6
+ --line: #e2e5ea;
7
+ --accent: #2f6fed;
8
+ --code-bg: #1e2430;
9
+ --code-text: #e8edf6;
10
+ }
11
+
12
+ * { box-sizing: border-box; }
13
+
14
+ html { scroll-behavior: smooth; }
15
+
16
+ body {
17
+ margin: 0;
18
+ background: var(--bg);
19
+ color: var(--text);
20
+ font: 15px/1.75 -apple-system, BlinkMacSystemFont, "Segoe UI", "Microsoft YaHei", sans-serif;
21
+ }
22
+
23
+ .sidebar {
24
+ position: fixed;
25
+ inset: 0 auto 0 0;
26
+ width: 248px;
27
+ padding: 28px 18px;
28
+ background: #171b23;
29
+ color: #cfd6e3;
30
+ overflow-y: auto;
31
+ }
32
+
33
+ .brand {
34
+ display: flex;
35
+ flex-direction: column;
36
+ margin-bottom: 24px;
37
+ }
38
+
39
+ .brand strong {
40
+ color: #fff;
41
+ font-size: 24px;
42
+ letter-spacing: 1px;
43
+ }
44
+
45
+ .brand span { color: #8791a5; font-size: 13px; }
46
+
47
+ .sidebar nav { display: flex; flex-direction: column; gap: 2px; }
48
+
49
+ .sidebar nav a {
50
+ color: #b9c2d2;
51
+ text-decoration: none;
52
+ padding: 7px 10px;
53
+ border-radius: 6px;
54
+ font-size: 14px;
55
+ }
56
+
57
+ .sidebar nav a:hover,
58
+ .sidebar nav a.active {
59
+ color: #fff;
60
+ background: #2a3140;
61
+ }
62
+
63
+ .version {
64
+ margin-top: 24px;
65
+ padding-top: 16px;
66
+ border-top: 1px solid #2a3140;
67
+ color: #7d8799;
68
+ font-size: 12px;
69
+ }
70
+
71
+ main {
72
+ max-width: 980px;
73
+ margin-left: 248px;
74
+ padding: 48px 56px 80px;
75
+ }
76
+
77
+ .hero {
78
+ padding: 30px 34px;
79
+ margin-bottom: 34px;
80
+ border: 1px solid var(--line);
81
+ border-radius: 14px;
82
+ background: linear-gradient(135deg, #fff, #eef3ff);
83
+ }
84
+
85
+ .hero h1 {
86
+ margin: 0 0 8px;
87
+ font-size: 34px;
88
+ letter-spacing: .5px;
89
+ }
90
+
91
+ .hero p { margin: 6px 0; color: var(--muted); }
92
+
93
+ .hero .note { color: #4d5b75; font-size: 13px; }
94
+
95
+ .page-header {
96
+ padding: 12px 2px 24px;
97
+ }
98
+
99
+ .page-header h1 {
100
+ margin: 6px 0 8px;
101
+ font-size: 32px;
102
+ }
103
+
104
+ .page-header p {
105
+ margin: 0;
106
+ color: var(--muted);
107
+ }
108
+
109
+ .breadcrumb {
110
+ color: #7b8494 !important;
111
+ font-size: 13px;
112
+ }
113
+
114
+ .page-grid {
115
+ display: grid;
116
+ grid-template-columns: repeat(2, minmax(0, 1fr));
117
+ gap: 14px;
118
+ margin-top: 14px;
119
+ }
120
+
121
+ .page-card {
122
+ display: block;
123
+ padding: 18px 20px;
124
+ border: 1px solid var(--line);
125
+ border-radius: 10px;
126
+ text-decoration: none;
127
+ color: var(--text);
128
+ background: #fbfcfe;
129
+ transition: border-color .15s, transform .15s, box-shadow .15s;
130
+ }
131
+
132
+ .page-card:hover {
133
+ border-color: #9db8f2;
134
+ transform: translateY(-1px);
135
+ box-shadow: 0 6px 18px rgba(47, 111, 237, .08);
136
+ }
137
+
138
+ .page-card h3 {
139
+ margin: 0 0 6px;
140
+ font-size: 17px;
141
+ }
142
+
143
+ .page-card p {
144
+ margin: 0;
145
+ color: var(--muted);
146
+ font-size: 14px;
147
+ }
148
+
149
+ @media (max-width: 640px) {
150
+ .page-grid { grid-template-columns: 1fr; }
151
+ }
152
+
153
+
154
+ section {
155
+ background: var(--panel);
156
+ border: 1px solid var(--line);
157
+ border-radius: 12px;
158
+ padding: 26px 30px;
159
+ margin-bottom: 22px;
160
+ scroll-margin-top: 20px;
161
+ }
162
+
163
+ h2 {
164
+ margin: 0 0 14px;
165
+ font-size: 22px;
166
+ color: #1d2635;
167
+ }
168
+
169
+ h3 {
170
+ margin: 22px 0 8px;
171
+ font-size: 16px;
172
+ color: #2b3444;
173
+ }
174
+
175
+ p { margin: 8px 0; color: #404652; }
176
+
177
+ ul, ol { margin: 8px 0; padding-left: 24px; color: #404652; }
178
+
179
+ code {
180
+ font-family: "Cascadia Code", Consolas, "Courier New", monospace;
181
+ font-size: .92em;
182
+ background: #eef1f6;
183
+ color: #24406e;
184
+ border-radius: 4px;
185
+ padding: 1px 5px;
186
+ }
187
+
188
+ pre {
189
+ margin: 12px 0;
190
+ padding: 16px 18px;
191
+ background: var(--code-bg);
192
+ color: var(--code-text);
193
+ border-radius: 9px;
194
+ overflow-x: auto;
195
+ line-height: 1.55;
196
+ }
197
+
198
+ pre code {
199
+ background: transparent;
200
+ color: inherit;
201
+ padding: 0;
202
+ font-size: 13px;
203
+ }
204
+
205
+ table {
206
+ width: 100%;
207
+ border-collapse: collapse;
208
+ margin: 12px 0;
209
+ font-size: 14px;
210
+ }
211
+
212
+ th, td {
213
+ text-align: left;
214
+ padding: 9px 10px;
215
+ border-bottom: 1px solid var(--line);
216
+ vertical-align: top;
217
+ }
218
+
219
+ th { color: #2b3444; background: #f7f9fc; }
220
+
221
+ footer {
222
+ color: var(--muted);
223
+ font-size: 13px;
224
+ padding: 10px 4px;
225
+ }
226
+
227
+ @media (max-width: 860px) {
228
+ .sidebar {
229
+ position: static;
230
+ width: auto;
231
+ height: auto;
232
+ }
233
+
234
+ .sidebar nav {
235
+ flex-direction: row;
236
+ flex-wrap: wrap;
237
+ }
238
+
239
+ main {
240
+ margin-left: 0;
241
+ padding: 24px 16px 48px;
242
+ }
243
+
244
+ section { padding: 20px 18px; }
245
+ .hero { padding: 22px 20px; }
246
+ }
@@ -0,0 +1,97 @@
1
+ <!DOCTYPE html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>工具与 FAQ · CCGF 使用文档</title>
7
+ <link rel="stylesheet" href="./style.css">
8
+ </head>
9
+ <body>
10
+ <aside class="sidebar">
11
+ <div class="brand"><strong>CCGF</strong><span>使用文档</span></div>
12
+ <nav>
13
+ <a href="./index.html" class="page-link">首页 / 快速开始</a>
14
+ <a href="./framework.html" class="page-link">框架核心</a>
15
+ <a href="./data.html" class="page-link">数据与流程</a>
16
+ <a href="./shared.html" class="page-link">公共模块</a>
17
+ <a href="./tools.html" class="page-link">工具与 FAQ</a>
18
+ </nav>
19
+ <div class="version">扩展工作台 · 目录约定 · FAQ</div>
20
+ </aside>
21
+
22
+ <main>
23
+ <header class="page-header">
24
+ <p class="breadcrumb">CCGF 使用文档 / 工具与 FAQ</p>
25
+ <h1>工具与 FAQ</h1>
26
+ <p>扩展工作台、目录约定和常见问题。</p>
27
+ </header>
28
+
29
+ <section id="extension">
30
+ <h2>扩展工作台</h2>
31
+ <ul>
32
+ <li>模块 / View / Manager 创建</li>
33
+ <li>目标 Bundle 切换</li>
34
+ <li>一键体检、启动顺序预览、公共模块安装</li>
35
+ <li>数据表工具:建骨架、导出、刷新</li>
36
+ <li>本地使用文档入口</li>
37
+ </ul>
38
+ <p>从菜单「开发工具」打开工作台、数据表工具或使用文档。</p>
39
+ </section>
40
+
41
+ <section id="paths">
42
+ <h2>创建目录约定</h2>
43
+ <pre><code>主包:
44
+ assets/scripts/gameplay/&lt;module&gt;/
45
+ assets/resources/views/&lt;module&gt;/
46
+
47
+ 子包:
48
+ assets/bundles/&lt;bundle&gt;/scripts/&lt;module&gt;/
49
+ assets/bundles/&lt;bundle&gt;/views/&lt;module&gt;/
50
+ </code></pre>
51
+ <p>创建前先在工作台顶部选目标 Bundle。主包模块不会生成到 <code>assets/scripts/&lt;module&gt;/</code>。</p>
52
+ </section>
53
+
54
+ <section id="build">
55
+ <h2>修改扩展 / 框架后</h2>
56
+ <pre><code># 扩展
57
+ cd extensions/ccgf-game-tool
58
+ npm run build
59
+
60
+ # 框架(开发工作区)
61
+ node tools/build-framework.js
62
+
63
+ # 公共模块
64
+ node tools/build-shared.js &lt;name&gt;
65
+
66
+ # 模板
67
+ node tools/build-template.js
68
+ </code></pre>
69
+ <p>扩展必须重启编辑器或重载扩展,否则运行的还是旧 <code>dist</code>。</p>
70
+ </section>
71
+
72
+ <section id="faq">
73
+ <h2>常见问题</h2>
74
+ <h3>为什么切场景后 View 都没了?</h3>
75
+ <p>View 是场景级 UI,旧场景销毁时会一起销毁。场景级界面在 <code>onSceneEnter</code> 重新 show;跨场景 UI 用常驻 Canvas(如 Loading),不要混用 ViewManager。</p>
76
+
77
+ <h3>为什么 Module.start 只执行一次?</h3>
78
+ <p>这是框架约定:<code>start</code> 负责数据/服务初始化,场景 UI 用 <code>onSceneEnter</code>。切回主场景不会重启模块。</p>
79
+
80
+ <h3>为什么创建模块没在指定目录?</h3>
81
+ <p>检查工作台顶部的目标 Bundle。主包模块在 <code>assets/scripts/gameplay/&lt;module&gt;/</code>,不是 <code>assets/scripts/&lt;module&gt;/</code>。</p>
82
+
83
+ <h3>Loading 为什么只覆盖设计分辨率?</h3>
84
+ <p>这是刻意的:Canvas 按设计分辨率布局,浏览器 letterbox 黑边不覆盖。需要全屏覆盖时,调整 Loading 的适配策略。</p>
85
+
86
+ <h3>公共模块安装后没有生效?</h3>
87
+ <p>确认包已经装进工程,且启动脚本 import 了模块入口;npm 包不会自动执行未 import 的脚本。</p>
88
+
89
+ <h3>任务系统 / 地图系统现在能用吗?</h3>
90
+ <p>任务运行时暂缓,见工程根 <code>docs/quest-todo.md</code>。地图只提供拓扑/寻路算法,MapData、关卡包、渲染和编辑器未实现,见 <code>docs/map-todo.md</code>。</p>
91
+ </section>
92
+
93
+ <footer><p>CCGF 本地文档 · 工具与 FAQ</p></footer>
94
+ </main>
95
+ <script src="./app.js"></script>
96
+ </body>
97
+ </html>
package/package.json CHANGED
@@ -7,7 +7,7 @@
7
7
  "dependencies": {
8
8
  "@ccgf/framework": "^0.1.14"
9
9
  },
10
- "version": "0.2.25",
10
+ "version": "0.2.27",
11
11
  "publishConfig": {
12
12
  "access": "public"
13
13
  },
@@ -21,6 +21,6 @@
21
21
  ]
22
22
  },
23
23
  "devDependencies": {
24
- "ccgf-game-tool": "^1.0.25"
24
+ "ccgf-game-tool": "^1.0.27"
25
25
  }
26
26
  }