ic10r-node 1.0.0 → 1.0.2
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.
- package/CHANGELOG.md +5 -5
- package/README.md +400 -400
- package/README.zh.md +400 -400
- package/package.json +1 -1
- package/types/context.d.ts +5 -2
- package/types/engine.d.ts +2 -0
- package/types/index.d.ts +1 -0
- package/types/memory.d.ts +3 -2
- package/types/value.d.ts +22 -0
package/README.zh.md
CHANGED
|
@@ -1,400 +1,400 @@
|
|
|
1
|
-
# ic10r_node
|
|
2
|
-
|
|
3
|
-
[](https://badge.fury.io/js/ic10r_node)
|
|
4
|
-
[](https://nodejs.org/)
|
|
5
|
-
[](https://isocpp.org/)
|
|
6
|
-
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
|
|
7
|
-
|
|
8
|
-
[English](README.md)
|
|
9
|
-
|
|
10
|
-
## 简介
|
|
11
|
-
|
|
12
|
-
`ic10r-node` 是 **IC10 运行时** 的 Node.js 原生绑定模块，提供了完整的 IC10 程序执行引擎。
|
|
13
|
-
|
|
14
|
-
IC10 是一种用于 [Stationeers](https://store.steampowered.com/app/544550/Stationeers/) 游戏的汇编式编程语言，用于控制游戏中的计算机和设备。本模块接收编译后的 AST 和符号表（由 [`ic10c-node`](https://www.npmjs.com/package/ic10c-node) 生成），逐 tick 执行程序，模拟 IC10 处理器的行为。
|
|
15
|
-
|
|
16
|
-
## 特性
|
|
17
|
-
|
|
18
|
-
- **执行引擎 (Engine)** - 逐 tick 执行（`runTick`）或一次性执行到结束（`runFull`）
|
|
19
|
-
- **寄存器文件和栈** - 完整的 16 寄存器文件（`r0`–`r15`）和栈内存（`push`/`pop`/`peek`/`poke`）
|
|
20
|
-
- **设备管理器 (Manager)** - 注册外部设备和芯片设备，按类型/名称哈希查询
|
|
21
|
-
- **设备 I/O** - 读写逻辑属性、设备栈、插槽和试剂模式
|
|
22
|
-
- **执行控制** - 支持 `halt`/`sleep`，可配置指令上限和 tick 时长
|
|
23
|
-
- **跨平台** - 支持 Linux (GCC/Clang) 和 Windows (MSVC)
|
|
24
|
-
|
|
25
|
-
## 安装
|
|
26
|
-
|
|
27
|
-
### 前提条件
|
|
28
|
-
|
|
29
|
-
- Node.js >= 16.0.0（推荐 Node.js 26.x）
|
|
30
|
-
- C++ 编译器 (GCC 13+ / Clang 16+ / MSVC 2022)
|
|
31
|
-
- CMake >= 3.28.1
|
|
32
|
-
- [`ic10c-node`](https://www.npmjs.com/package/ic10c-node)（编译阶段的依赖）
|
|
33
|
-
|
|
34
|
-
### 从 npm 安装
|
|
35
|
-
|
|
36
|
-
```bash
|
|
37
|
-
npm install ic10r-node ic10c-node
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
### 从源码构建
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
# 克隆仓库
|
|
44
|
-
git clone https://github.com/edoCsItahW/Stationeers.git
|
|
45
|
-
cd Stationeers/code/IC10/backend/runtime
|
|
46
|
-
|
|
47
|
-
# 安装依赖
|
|
48
|
-
npm install
|
|
49
|
-
|
|
50
|
-
# 下载 Node.js 头文件
|
|
51
|
-
npx node-gyp install
|
|
52
|
-
|
|
53
|
-
# 构建原生模块
|
|
54
|
-
npm run build
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
## 快速开始
|
|
58
|
-
|
|
59
|
-
### 基本用法
|
|
60
|
-
|
|
61
|
-
```typescript
|
|
62
|
-
import * as ic10c from 'ic10c-node';
|
|
63
|
-
import * as ic10r from 'ic10r-node';
|
|
64
|
-
|
|
65
|
-
// IC10 源代码
|
|
66
|
-
const source = `
|
|
67
|
-
main:
|
|
68
|
-
move r0 42
|
|
69
|
-
add r1 r0 10
|
|
70
|
-
hcf
|
|
71
|
-
`;
|
|
72
|
-
|
|
73
|
-
// 1. 编译（使用 ic10c-node）
|
|
74
|
-
const tokens = ic10c.Lexer.tokenize(source);
|
|
75
|
-
const program = new ic10c.Parser(tokens).parse();
|
|
76
|
-
const analyser = new ic10c.Analyser();
|
|
77
|
-
await analyser.visit(program);
|
|
78
|
-
|
|
79
|
-
// 2. 创建引擎（使用 ic10r-node）
|
|
80
|
-
const engine = new ic10r.Engine(program, analyser.symbolTable);
|
|
81
|
-
|
|
82
|
-
// 3. 执行
|
|
83
|
-
engine.runFull();
|
|
84
|
-
|
|
85
|
-
// 4. 查看结果
|
|
86
|
-
const r0 = engine.context.memory.getReg('r0'); // 42
|
|
87
|
-
const r1 = engine.context.memory.getReg('r1'); // 52
|
|
88
|
-
console.log(`r0 = ${r0}, r1 = ${r1}`);
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
### 逐 Tick 执行
|
|
92
|
-
|
|
93
|
-
```typescript
|
|
94
|
-
import * as ic10c from 'ic10c-node';
|
|
95
|
-
import * as ic10r from 'ic10r-node';
|
|
96
|
-
|
|
97
|
-
const source = `
|
|
98
|
-
loop:
|
|
99
|
-
move r0 1
|
|
100
|
-
yield
|
|
101
|
-
jal loop
|
|
102
|
-
`;
|
|
103
|
-
|
|
104
|
-
const tokens = ic10c.Lexer.tokenize(source);
|
|
105
|
-
const program = new ic10c.Parser(tokens).parse();
|
|
106
|
-
const analyser = new ic10c.Analyser();
|
|
107
|
-
await analyser.visit(program);
|
|
108
|
-
|
|
109
|
-
const engine = new ic10r.Engine(program, analyser.symbolTable);
|
|
110
|
-
|
|
111
|
-
// 逐 tick 执行
|
|
112
|
-
engine.runTick(); // 执行一个 tick
|
|
113
|
-
engine.runTick(); // 执行下一个 tick
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
### 设备交互
|
|
117
|
-
|
|
118
|
-
```typescript
|
|
119
|
-
import * as ic10c from 'ic10c-node';
|
|
120
|
-
import * as ic10r from 'ic10r-node';
|
|
121
|
-
|
|
122
|
-
const source = `
|
|
123
|
-
alias led d0
|
|
124
|
-
main:
|
|
125
|
-
s led Setting 1
|
|
126
|
-
hcf
|
|
127
|
-
`;
|
|
128
|
-
|
|
129
|
-
const tokens = ic10c.Lexer.tokenize(source);
|
|
130
|
-
const program = new ic10c.Parser(tokens).parse();
|
|
131
|
-
const analyser = new ic10c.Analyser();
|
|
132
|
-
await analyser.visit(program);
|
|
133
|
-
|
|
134
|
-
const engine = new ic10r.Engine(program, analyser.symbolTable);
|
|
135
|
-
|
|
136
|
-
// 注册外部设备
|
|
137
|
-
const device = engine.context.manager.getDevice('d0');
|
|
138
|
-
engine.context.manager.setExternalDevice('d0', device);
|
|
139
|
-
|
|
140
|
-
engine.runFull();
|
|
141
|
-
|
|
142
|
-
// 执行后读取设备逻辑
|
|
143
|
-
console.log(device.readLogic('Setting')); // 1
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
## API 文档
|
|
147
|
-
|
|
148
|
-
### 类
|
|
149
|
-
|
|
150
|
-
| 类 | 说明 |
|
|
151
|
-
|:---|:---|
|
|
152
|
-
| `Engine` | IC10 程序执行引擎 |
|
|
153
|
-
| `Context` | 执行上下文（PC、内存、管理器） |
|
|
154
|
-
| `Memory` | 寄存器文件和栈内存 |
|
|
155
|
-
| `Manager` | 设备管理器 |
|
|
156
|
-
| `Device` | 设备 I/O 接口（逻辑、插槽、试剂） |
|
|
157
|
-
|
|
158
|
-
### Config
|
|
159
|
-
|
|
160
|
-
```typescript
|
|
161
|
-
import type { Config } from 'ic10r-node';
|
|
162
|
-
|
|
163
|
-
const config: Config = {
|
|
164
|
-
tickDuration: 0.5, // 每 tick 秒数
|
|
165
|
-
maxInstructions: 128, // 每 tick 最大指令数
|
|
166
|
-
maxStackSize: 512 // 最大栈大小
|
|
167
|
-
};
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
### Engine
|
|
171
|
-
|
|
172
|
-
```typescript
|
|
173
|
-
import { Engine } from 'ic10r-node';
|
|
174
|
-
import type { Program, SymbolTable } from 'ic10c-node';
|
|
175
|
-
|
|
176
|
-
// 创建引擎，可选配置
|
|
177
|
-
const engine = new Engine(program, symbolTable, {
|
|
178
|
-
tickDuration: 0.5,
|
|
179
|
-
maxInstructions: 128
|
|
180
|
-
});
|
|
181
|
-
|
|
182
|
-
// 执行
|
|
183
|
-
engine.runTick(); // 一个 tick
|
|
184
|
-
engine.runFull(); // 执行到 halt
|
|
185
|
-
|
|
186
|
-
// 访问上下文
|
|
187
|
-
const ctx = engine.context;
|
|
188
|
-
console.log(ctx.pc); // 程序计数器
|
|
189
|
-
console.log(ctx.halted); // 停机标志
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
### Context
|
|
193
|
-
|
|
194
|
-
```typescript
|
|
195
|
-
const ctx = engine.context;
|
|
196
|
-
|
|
197
|
-
// 程序计数器
|
|
198
|
-
ctx.pc = 0;
|
|
199
|
-
|
|
200
|
-
// 内存访问
|
|
201
|
-
const memory = ctx.memory;
|
|
202
|
-
|
|
203
|
-
// 设备管理器
|
|
204
|
-
const manager = ctx.manager;
|
|
205
|
-
|
|
206
|
-
// 执行控制
|
|
207
|
-
ctx.halt(); // 停止执行
|
|
208
|
-
ctx.sleep(1.0); // 休眠 1 秒
|
|
209
|
-
console.log(ctx.isSleeping);
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
### Memory
|
|
213
|
-
|
|
214
|
-
```typescript
|
|
215
|
-
const mem = engine.context.memory;
|
|
216
|
-
|
|
217
|
-
// 寄存器访问
|
|
218
|
-
mem.setReg('r0', 42);
|
|
219
|
-
const r0 = mem.getReg('r0'); // 42
|
|
220
|
-
|
|
221
|
-
// 栈操作
|
|
222
|
-
mem.push(100);
|
|
223
|
-
mem.push(200);
|
|
224
|
-
const top = mem.peek(); // 200
|
|
225
|
-
const val = mem.pop(); // 200
|
|
226
|
-
|
|
227
|
-
// 直接栈访问
|
|
228
|
-
mem.setStack(0, 999);
|
|
229
|
-
const s0 = mem.getStack(0); // 999
|
|
230
|
-
|
|
231
|
-
// 序列化
|
|
232
|
-
const json = mem.toJSON();
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
### Manager
|
|
236
|
-
|
|
237
|
-
```typescript
|
|
238
|
-
const mgr = engine.context.manager;
|
|
239
|
-
|
|
240
|
-
// 设备注册
|
|
241
|
-
mgr.setExternalDevice('d0', device);
|
|
242
|
-
mgr.setChipDevice(chipDevice);
|
|
243
|
-
|
|
244
|
-
// 设备查找
|
|
245
|
-
const dev = mgr.getDevice('d0');
|
|
246
|
-
const found = mgr.findDeviceByType(typeHash);
|
|
247
|
-
const all = mgr.findDevicesByType(typeHash);
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
### Device
|
|
251
|
-
|
|
252
|
-
```typescript
|
|
253
|
-
const dev = mgr.getDevice('d0');
|
|
254
|
-
|
|
255
|
-
// 逻辑属性
|
|
256
|
-
dev.writeLogic('Setting', 1);
|
|
257
|
-
const val = dev.readLogic('Setting');
|
|
258
|
-
|
|
259
|
-
// 设备栈
|
|
260
|
-
dev.writeStack(0, 42);
|
|
261
|
-
const s0 = dev.readStack(0);
|
|
262
|
-
|
|
263
|
-
// 插槽
|
|
264
|
-
dev.writeSlot(0, 'Occupied', 1);
|
|
265
|
-
const occ = dev.readSlot(0, 'Occupied');
|
|
266
|
-
|
|
267
|
-
// 试剂
|
|
268
|
-
const mode = dev.readReagent(0);
|
|
269
|
-
const amount = dev.queryReagentAmount(reagentHash);
|
|
270
|
-
|
|
271
|
-
// 元数据
|
|
272
|
-
const typeHash = dev.getTypeHash();
|
|
273
|
-
const nameHash = dev.getNameHash();
|
|
274
|
-
|
|
275
|
-
// 生命周期
|
|
276
|
-
dev.tick();
|
|
277
|
-
dev.clearStack();
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
## IC10 指令示例
|
|
281
|
-
|
|
282
|
-
### 算术运算
|
|
283
|
-
|
|
284
|
-
```ic10
|
|
285
|
-
move r0 10
|
|
286
|
-
move r1 20
|
|
287
|
-
add r2 r0 r1 # r2 = 30
|
|
288
|
-
sub r3 r2 5 # r3 = 25
|
|
289
|
-
mul r4 r3 2 # r4 = 50
|
|
290
|
-
div r5 r4 5 # r5 = 10
|
|
291
|
-
```
|
|
292
|
-
|
|
293
|
-
### 控制流
|
|
294
|
-
|
|
295
|
-
```ic10
|
|
296
|
-
loop:
|
|
297
|
-
move r0 1
|
|
298
|
-
yield
|
|
299
|
-
jal loop
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
### 设备 I/O
|
|
303
|
-
|
|
304
|
-
```ic10
|
|
305
|
-
alias led d0
|
|
306
|
-
s led Setting 1
|
|
307
|
-
r r0 led Setting
|
|
308
|
-
```
|
|
309
|
-
|
|
310
|
-
## TypeScript
|
|
311
|
-
|
|
312
|
-
本模块附带完整的 TypeScript 类型定义，无需额外安装 `@types` 包。
|
|
313
|
-
|
|
314
|
-
```typescript
|
|
315
|
-
import { Engine, Context, Memory, Manager, Device } from 'ic10r-node';
|
|
316
|
-
import type { Config } from 'ic10r-node';
|
|
317
|
-
|
|
318
|
-
const config: Config = {
|
|
319
|
-
tickDuration: 0.5,
|
|
320
|
-
maxInstructions: 128,
|
|
321
|
-
maxStackSize: 512
|
|
322
|
-
};
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
## 构建说明
|
|
326
|
-
|
|
327
|
-
### 环境要求
|
|
328
|
-
|
|
329
|
-
- **Node.js**: 16.0.0+
|
|
330
|
-
- **CMake**: 3.28.1+
|
|
331
|
-
- **C++ 编译器**:
|
|
332
|
-
- Linux: GCC 13+ 或 Clang 16+
|
|
333
|
-
- Windows: MSVC 2022
|
|
334
|
-
|
|
335
|
-
### 构建步骤
|
|
336
|
-
|
|
337
|
-
```bash
|
|
338
|
-
# 1. 安装 Node.js 依赖
|
|
339
|
-
npm install
|
|
340
|
-
|
|
341
|
-
# 2. 下载 Node.js 头文件
|
|
342
|
-
npx node-gyp install
|
|
343
|
-
|
|
344
|
-
# 3. 配置 CMake
|
|
345
|
-
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
|
|
346
|
-
|
|
347
|
-
# 4. 编译
|
|
348
|
-
cmake --build build --parallel 4
|
|
349
|
-
|
|
350
|
-
# 5. 复制生成的 .node 文件
|
|
351
|
-
cp build/ic10r-node.node src/
|
|
352
|
-
```
|
|
353
|
-
|
|
354
|
-
## 项目结构
|
|
355
|
-
|
|
356
|
-
```
|
|
357
|
-
ic10r-node/
|
|
358
|
-
├── src/
|
|
359
|
-
│ └── ic10r-node.node # 原生模块（编译生成）
|
|
360
|
-
├── types/
|
|
361
|
-
│ ├── index.d.ts # TypeScript 类型定义（入口）
|
|
362
|
-
│ ├── config.d.ts # Config 接口
|
|
363
|
-
│ ├── context.d.ts # Context 类
|
|
364
|
-
│ ├── device.d.ts # Device 类
|
|
365
|
-
│ ├── engine.d.ts # Engine 类
|
|
366
|
-
│ ├── manager.d.ts # Manager 类
|
|
367
|
-
│ └── memory.d.ts # Memory 类
|
|
368
|
-
├── tsconfig.json
|
|
369
|
-
├── package.json
|
|
370
|
-
└── README.md
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
## 许可证
|
|
374
|
-
|
|
375
|
-
本项目采用 **CC BY-NC-SA 4.0** (Creative Commons Attribution-NonCommercial-ShareAlike 4.0) 许可证。
|
|
376
|
-
|
|
377
|
-
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
|
|
378
|
-
|
|
379
|
-
## 贡献
|
|
380
|
-
|
|
381
|
-
欢迎提交 Issue 和 Pull Request！
|
|
382
|
-
|
|
383
|
-
1. Fork 本仓库
|
|
384
|
-
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
|
|
385
|
-
3. 提交更改 (`git commit -m 'Add amazing feature'`)
|
|
386
|
-
4. 推送到分支 (`git push origin feature/amazing-feature`)
|
|
387
|
-
5. 创建 Pull Request
|
|
388
|
-
|
|
389
|
-
## 联系方式
|
|
390
|
-
|
|
391
|
-
- **作者**: edocsitahw
|
|
392
|
-
- **邮箱**: edocsitahw@qq.com
|
|
393
|
-
- **仓库**: [https://github.com/edoCsItahW/Stationeers](https://github.com/edoCsItahW/Stationeers)
|
|
394
|
-
|
|
395
|
-
## 相关链接
|
|
396
|
-
|
|
397
|
-
- [ic10c-node – IC10 编译器 Node.js 绑定](https://www.npmjs.com/package/ic10c-node)
|
|
398
|
-
- [Stationeers 官方网站](https://store.steampowered.com/app/544550/Stationeers/)
|
|
399
|
-
- [Node.js N-API 文档](https://nodejs.org/api/n-api.html)
|
|
400
|
-
- [node-addon-api 文档](https://github.com/nodejs/node-addon-api)
|
|
1
|
+
# ic10r_node
|
|
2
|
+
|
|
3
|
+
[](https://badge.fury.io/js/ic10r_node)
|
|
4
|
+
[](https://nodejs.org/)
|
|
5
|
+
[](https://isocpp.org/)
|
|
6
|
+
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
|
|
7
|
+
|
|
8
|
+
[English](README.md)
|
|
9
|
+
|
|
10
|
+
## 简介
|
|
11
|
+
|
|
12
|
+
`ic10r-node` 是 **IC10 运行时** 的 Node.js 原生绑定模块，提供了完整的 IC10 程序执行引擎。
|
|
13
|
+
|
|
14
|
+
IC10 是一种用于 [Stationeers](https://store.steampowered.com/app/544550/Stationeers/) 游戏的汇编式编程语言，用于控制游戏中的计算机和设备。本模块接收编译后的 AST 和符号表（由 [`ic10c-node`](https://www.npmjs.com/package/ic10c-node) 生成），逐 tick 执行程序，模拟 IC10 处理器的行为。
|
|
15
|
+
|
|
16
|
+
## 特性
|
|
17
|
+
|
|
18
|
+
- **执行引擎 (Engine)** - 逐 tick 执行（`runTick`）或一次性执行到结束（`runFull`）
|
|
19
|
+
- **寄存器文件和栈** - 完整的 16 寄存器文件（`r0`–`r15`）和栈内存（`push`/`pop`/`peek`/`poke`）
|
|
20
|
+
- **设备管理器 (Manager)** - 注册外部设备和芯片设备，按类型/名称哈希查询
|
|
21
|
+
- **设备 I/O** - 读写逻辑属性、设备栈、插槽和试剂模式
|
|
22
|
+
- **执行控制** - 支持 `halt`/`sleep`，可配置指令上限和 tick 时长
|
|
23
|
+
- **跨平台** - 支持 Linux (GCC/Clang) 和 Windows (MSVC)
|
|
24
|
+
|
|
25
|
+
## 安装
|
|
26
|
+
|
|
27
|
+
### 前提条件
|
|
28
|
+
|
|
29
|
+
- Node.js >= 16.0.0（推荐 Node.js 26.x）
|
|
30
|
+
- C++ 编译器 (GCC 13+ / Clang 16+ / MSVC 2022)
|
|
31
|
+
- CMake >= 3.28.1
|
|
32
|
+
- [`ic10c-node`](https://www.npmjs.com/package/ic10c-node)（编译阶段的依赖）
|
|
33
|
+
|
|
34
|
+
### 从 npm 安装
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npm install ic10r-node ic10c-node
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### 从源码构建
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# 克隆仓库
|
|
44
|
+
git clone https://github.com/edoCsItahW/Stationeers.git
|
|
45
|
+
cd Stationeers/code/IC10/backend/runtime
|
|
46
|
+
|
|
47
|
+
# 安装依赖
|
|
48
|
+
npm install
|
|
49
|
+
|
|
50
|
+
# 下载 Node.js 头文件
|
|
51
|
+
npx node-gyp install
|
|
52
|
+
|
|
53
|
+
# 构建原生模块
|
|
54
|
+
npm run build
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## 快速开始
|
|
58
|
+
|
|
59
|
+
### 基本用法
|
|
60
|
+
|
|
61
|
+
```typescript
|
|
62
|
+
import * as ic10c from 'ic10c-node';
|
|
63
|
+
import * as ic10r from 'ic10r-node';
|
|
64
|
+
|
|
65
|
+
// IC10 源代码
|
|
66
|
+
const source = `
|
|
67
|
+
main:
|
|
68
|
+
move r0 42
|
|
69
|
+
add r1 r0 10
|
|
70
|
+
hcf
|
|
71
|
+
`;
|
|
72
|
+
|
|
73
|
+
// 1. 编译（使用 ic10c-node）
|
|
74
|
+
const tokens = ic10c.Lexer.tokenize(source);
|
|
75
|
+
const program = new ic10c.Parser(tokens).parse();
|
|
76
|
+
const analyser = new ic10c.Analyser();
|
|
77
|
+
await analyser.visit(program);
|
|
78
|
+
|
|
79
|
+
// 2. 创建引擎（使用 ic10r-node）
|
|
80
|
+
const engine = new ic10r.Engine(program, analyser.symbolTable);
|
|
81
|
+
|
|
82
|
+
// 3. 执行
|
|
83
|
+
engine.runFull();
|
|
84
|
+
|
|
85
|
+
// 4. 查看结果
|
|
86
|
+
const r0 = engine.context.memory.getReg('r0'); // 42
|
|
87
|
+
const r1 = engine.context.memory.getReg('r1'); // 52
|
|
88
|
+
console.log(`r0 = ${r0}, r1 = ${r1}`);
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### 逐 Tick 执行
|
|
92
|
+
|
|
93
|
+
```typescript
|
|
94
|
+
import * as ic10c from 'ic10c-node';
|
|
95
|
+
import * as ic10r from 'ic10r-node';
|
|
96
|
+
|
|
97
|
+
const source = `
|
|
98
|
+
loop:
|
|
99
|
+
move r0 1
|
|
100
|
+
yield
|
|
101
|
+
jal loop
|
|
102
|
+
`;
|
|
103
|
+
|
|
104
|
+
const tokens = ic10c.Lexer.tokenize(source);
|
|
105
|
+
const program = new ic10c.Parser(tokens).parse();
|
|
106
|
+
const analyser = new ic10c.Analyser();
|
|
107
|
+
await analyser.visit(program);
|
|
108
|
+
|
|
109
|
+
const engine = new ic10r.Engine(program, analyser.symbolTable);
|
|
110
|
+
|
|
111
|
+
// 逐 tick 执行
|
|
112
|
+
engine.runTick(); // 执行一个 tick
|
|
113
|
+
engine.runTick(); // 执行下一个 tick
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### 设备交互
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
119
|
+
import * as ic10c from 'ic10c-node';
|
|
120
|
+
import * as ic10r from 'ic10r-node';
|
|
121
|
+
|
|
122
|
+
const source = `
|
|
123
|
+
alias led d0
|
|
124
|
+
main:
|
|
125
|
+
s led Setting 1
|
|
126
|
+
hcf
|
|
127
|
+
`;
|
|
128
|
+
|
|
129
|
+
const tokens = ic10c.Lexer.tokenize(source);
|
|
130
|
+
const program = new ic10c.Parser(tokens).parse();
|
|
131
|
+
const analyser = new ic10c.Analyser();
|
|
132
|
+
await analyser.visit(program);
|
|
133
|
+
|
|
134
|
+
const engine = new ic10r.Engine(program, analyser.symbolTable);
|
|
135
|
+
|
|
136
|
+
// 注册外部设备
|
|
137
|
+
const device = engine.context.manager.getDevice('d0');
|
|
138
|
+
engine.context.manager.setExternalDevice('d0', device);
|
|
139
|
+
|
|
140
|
+
engine.runFull();
|
|
141
|
+
|
|
142
|
+
// 执行后读取设备逻辑
|
|
143
|
+
console.log(device.readLogic('Setting')); // 1
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## API 文档
|
|
147
|
+
|
|
148
|
+
### 类
|
|
149
|
+
|
|
150
|
+
| 类 | 说明 |
|
|
151
|
+
|:---|:---|
|
|
152
|
+
| `Engine` | IC10 程序执行引擎 |
|
|
153
|
+
| `Context` | 执行上下文（PC、内存、管理器） |
|
|
154
|
+
| `Memory` | 寄存器文件和栈内存 |
|
|
155
|
+
| `Manager` | 设备管理器 |
|
|
156
|
+
| `Device` | 设备 I/O 接口（逻辑、插槽、试剂） |
|
|
157
|
+
|
|
158
|
+
### Config
|
|
159
|
+
|
|
160
|
+
```typescript
|
|
161
|
+
import type { Config } from 'ic10r-node';
|
|
162
|
+
|
|
163
|
+
const config: Config = {
|
|
164
|
+
tickDuration: 0.5, // 每 tick 秒数
|
|
165
|
+
maxInstructions: 128, // 每 tick 最大指令数
|
|
166
|
+
maxStackSize: 512 // 最大栈大小
|
|
167
|
+
};
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### Engine
|
|
171
|
+
|
|
172
|
+
```typescript
|
|
173
|
+
import { Engine } from 'ic10r-node';
|
|
174
|
+
import type { Program, SymbolTable } from 'ic10c-node';
|
|
175
|
+
|
|
176
|
+
// 创建引擎，可选配置
|
|
177
|
+
const engine = new Engine(program, symbolTable, {
|
|
178
|
+
tickDuration: 0.5,
|
|
179
|
+
maxInstructions: 128
|
|
180
|
+
});
|
|
181
|
+
|
|
182
|
+
// 执行
|
|
183
|
+
engine.runTick(); // 一个 tick
|
|
184
|
+
engine.runFull(); // 执行到 halt
|
|
185
|
+
|
|
186
|
+
// 访问上下文
|
|
187
|
+
const ctx = engine.context;
|
|
188
|
+
console.log(ctx.pc); // 程序计数器
|
|
189
|
+
console.log(ctx.halted); // 停机标志
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Context
|
|
193
|
+
|
|
194
|
+
```typescript
|
|
195
|
+
const ctx = engine.context;
|
|
196
|
+
|
|
197
|
+
// 程序计数器
|
|
198
|
+
ctx.pc = 0;
|
|
199
|
+
|
|
200
|
+
// 内存访问
|
|
201
|
+
const memory = ctx.memory;
|
|
202
|
+
|
|
203
|
+
// 设备管理器
|
|
204
|
+
const manager = ctx.manager;
|
|
205
|
+
|
|
206
|
+
// 执行控制
|
|
207
|
+
ctx.halt(); // 停止执行
|
|
208
|
+
ctx.sleep(1.0); // 休眠 1 秒
|
|
209
|
+
console.log(ctx.isSleeping);
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### Memory
|
|
213
|
+
|
|
214
|
+
```typescript
|
|
215
|
+
const mem = engine.context.memory;
|
|
216
|
+
|
|
217
|
+
// 寄存器访问
|
|
218
|
+
mem.setReg('r0', 42);
|
|
219
|
+
const r0 = mem.getReg('r0'); // 42
|
|
220
|
+
|
|
221
|
+
// 栈操作
|
|
222
|
+
mem.push(100);
|
|
223
|
+
mem.push(200);
|
|
224
|
+
const top = mem.peek(); // 200
|
|
225
|
+
const val = mem.pop(); // 200
|
|
226
|
+
|
|
227
|
+
// 直接栈访问
|
|
228
|
+
mem.setStack(0, 999);
|
|
229
|
+
const s0 = mem.getStack(0); // 999
|
|
230
|
+
|
|
231
|
+
// 序列化
|
|
232
|
+
const json = mem.toJSON();
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
### Manager
|
|
236
|
+
|
|
237
|
+
```typescript
|
|
238
|
+
const mgr = engine.context.manager;
|
|
239
|
+
|
|
240
|
+
// 设备注册
|
|
241
|
+
mgr.setExternalDevice('d0', device);
|
|
242
|
+
mgr.setChipDevice(chipDevice);
|
|
243
|
+
|
|
244
|
+
// 设备查找
|
|
245
|
+
const dev = mgr.getDevice('d0');
|
|
246
|
+
const found = mgr.findDeviceByType(typeHash);
|
|
247
|
+
const all = mgr.findDevicesByType(typeHash);
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### Device
|
|
251
|
+
|
|
252
|
+
```typescript
|
|
253
|
+
const dev = mgr.getDevice('d0');
|
|
254
|
+
|
|
255
|
+
// 逻辑属性
|
|
256
|
+
dev.writeLogic('Setting', 1);
|
|
257
|
+
const val = dev.readLogic('Setting');
|
|
258
|
+
|
|
259
|
+
// 设备栈
|
|
260
|
+
dev.writeStack(0, 42);
|
|
261
|
+
const s0 = dev.readStack(0);
|
|
262
|
+
|
|
263
|
+
// 插槽
|
|
264
|
+
dev.writeSlot(0, 'Occupied', 1);
|
|
265
|
+
const occ = dev.readSlot(0, 'Occupied');
|
|
266
|
+
|
|
267
|
+
// 试剂
|
|
268
|
+
const mode = dev.readReagent(0);
|
|
269
|
+
const amount = dev.queryReagentAmount(reagentHash);
|
|
270
|
+
|
|
271
|
+
// 元数据
|
|
272
|
+
const typeHash = dev.getTypeHash();
|
|
273
|
+
const nameHash = dev.getNameHash();
|
|
274
|
+
|
|
275
|
+
// 生命周期
|
|
276
|
+
dev.tick();
|
|
277
|
+
dev.clearStack();
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
## IC10 指令示例
|
|
281
|
+
|
|
282
|
+
### 算术运算
|
|
283
|
+
|
|
284
|
+
```ic10
|
|
285
|
+
move r0 10
|
|
286
|
+
move r1 20
|
|
287
|
+
add r2 r0 r1 # r2 = 30
|
|
288
|
+
sub r3 r2 5 # r3 = 25
|
|
289
|
+
mul r4 r3 2 # r4 = 50
|
|
290
|
+
div r5 r4 5 # r5 = 10
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
### 控制流
|
|
294
|
+
|
|
295
|
+
```ic10
|
|
296
|
+
loop:
|
|
297
|
+
move r0 1
|
|
298
|
+
yield
|
|
299
|
+
jal loop
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### 设备 I/O
|
|
303
|
+
|
|
304
|
+
```ic10
|
|
305
|
+
alias led d0
|
|
306
|
+
s led Setting 1
|
|
307
|
+
r r0 led Setting
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
## TypeScript
|
|
311
|
+
|
|
312
|
+
本模块附带完整的 TypeScript 类型定义，无需额外安装 `@types` 包。
|
|
313
|
+
|
|
314
|
+
```typescript
|
|
315
|
+
import { Engine, Context, Memory, Manager, Device } from 'ic10r-node';
|
|
316
|
+
import type { Config } from 'ic10r-node';
|
|
317
|
+
|
|
318
|
+
const config: Config = {
|
|
319
|
+
tickDuration: 0.5,
|
|
320
|
+
maxInstructions: 128,
|
|
321
|
+
maxStackSize: 512
|
|
322
|
+
};
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
## 构建说明
|
|
326
|
+
|
|
327
|
+
### 环境要求
|
|
328
|
+
|
|
329
|
+
- **Node.js**: 16.0.0+
|
|
330
|
+
- **CMake**: 3.28.1+
|
|
331
|
+
- **C++ 编译器**:
|
|
332
|
+
- Linux: GCC 13+ 或 Clang 16+
|
|
333
|
+
- Windows: MSVC 2022
|
|
334
|
+
|
|
335
|
+
### 构建步骤
|
|
336
|
+
|
|
337
|
+
```bash
|
|
338
|
+
# 1. 安装 Node.js 依赖
|
|
339
|
+
npm install
|
|
340
|
+
|
|
341
|
+
# 2. 下载 Node.js 头文件
|
|
342
|
+
npx node-gyp install
|
|
343
|
+
|
|
344
|
+
# 3. 配置 CMake
|
|
345
|
+
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
|
|
346
|
+
|
|
347
|
+
# 4. 编译
|
|
348
|
+
cmake --build build --parallel 4
|
|
349
|
+
|
|
350
|
+
# 5. 复制生成的 .node 文件
|
|
351
|
+
cp build/ic10r-node.node src/
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
## 项目结构
|
|
355
|
+
|
|
356
|
+
```
|
|
357
|
+
ic10r-node/
|
|
358
|
+
├── src/
|
|
359
|
+
│ └── ic10r-node.node # 原生模块（编译生成）
|
|
360
|
+
├── types/
|
|
361
|
+
│ ├── index.d.ts # TypeScript 类型定义（入口）
|
|
362
|
+
│ ├── config.d.ts # Config 接口
|
|
363
|
+
│ ├── context.d.ts # Context 类
|
|
364
|
+
│ ├── device.d.ts # Device 类
|
|
365
|
+
│ ├── engine.d.ts # Engine 类
|
|
366
|
+
│ ├── manager.d.ts # Manager 类
|
|
367
|
+
│ └── memory.d.ts # Memory 类
|
|
368
|
+
├── tsconfig.json
|
|
369
|
+
├── package.json
|
|
370
|
+
└── README.md
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
## 许可证
|
|
374
|
+
|
|
375
|
+
本项目采用 **CC BY-NC-SA 4.0** (Creative Commons Attribution-NonCommercial-ShareAlike 4.0) 许可证。
|
|
376
|
+
|
|
377
|
+
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
|
|
378
|
+
|
|
379
|
+
## 贡献
|
|
380
|
+
|
|
381
|
+
欢迎提交 Issue 和 Pull Request！
|
|
382
|
+
|
|
383
|
+
1. Fork 本仓库
|
|
384
|
+
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
|
|
385
|
+
3. 提交更改 (`git commit -m 'Add amazing feature'`)
|
|
386
|
+
4. 推送到分支 (`git push origin feature/amazing-feature`)
|
|
387
|
+
5. 创建 Pull Request
|
|
388
|
+
|
|
389
|
+
## 联系方式
|
|
390
|
+
|
|
391
|
+
- **作者**: edocsitahw
|
|
392
|
+
- **邮箱**: edocsitahw@qq.com
|
|
393
|
+
- **仓库**: [https://github.com/edoCsItahW/Stationeers](https://github.com/edoCsItahW/Stationeers)
|
|
394
|
+
|
|
395
|
+
## 相关链接
|
|
396
|
+
|
|
397
|
+
- [ic10c-node – IC10 编译器 Node.js 绑定](https://www.npmjs.com/package/ic10c-node)
|
|
398
|
+
- [Stationeers 官方网站](https://store.steampowered.com/app/544550/Stationeers/)
|
|
399
|
+
- [Node.js N-API 文档](https://nodejs.org/api/n-api.html)
|
|
400
|
+
- [node-addon-api 文档](https://github.com/nodejs/node-addon-api)
|