sfml.js 1.0.0-rc.2 → 1.1.0
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/README.ja.md +16 -11
- package/README.ko.md +16 -11
- package/README.md +16 -11
- package/README.zh-CN.md +16 -11
- package/assets/breakout.png +0 -0
- package/binding.gyp +23 -16
- package/dist/audio/effect-processor.js +9 -3
- package/dist/audio/input-sound-file.js +41 -15
- package/dist/audio/listener.js +33 -11
- package/dist/audio/music.js +41 -18
- package/dist/audio/output-sound-file.js +4 -2
- package/dist/audio/playback-device.js +11 -3
- package/dist/audio/sound-buffer-recorder.js +8 -5
- package/dist/audio/sound-buffer.js +40 -17
- package/dist/audio/sound-file-factory.js +21 -9
- package/dist/audio/sound-file-reader.js +21 -7
- package/dist/audio/sound-recorder.js +36 -15
- package/dist/audio/sound-source.js +117 -40
- package/dist/audio/sound-stream.js +14 -5
- package/dist/audio/sound.js +9 -4
- package/dist/audio/value.js +42 -16
- package/dist/graphics/blend-mode.js +2 -1
- package/dist/graphics/boolean-vector.d.ts +1 -2
- package/dist/graphics/boolean-vector.js +19 -9
- package/dist/graphics/color.js +2 -1
- package/dist/graphics/convex-shape.js +7 -3
- package/dist/graphics/font.js +52 -23
- package/dist/graphics/glsl-matrix.js +8 -3
- package/dist/graphics/glsl.js +47 -16
- package/dist/graphics/glyph.js +27 -10
- package/dist/graphics/image.js +30 -14
- package/dist/graphics/rect.js +15 -8
- package/dist/graphics/render-states.js +18 -9
- package/dist/graphics/render-target.js +49 -23
- package/dist/graphics/render-texture.js +24 -12
- package/dist/graphics/render-window.js +6 -3
- package/dist/graphics/shader.js +67 -32
- package/dist/graphics/shape.js +25 -13
- package/dist/graphics/sprite.js +19 -9
- package/dist/graphics/stencil-mode.js +10 -6
- package/dist/graphics/swap.js +2 -1
- package/dist/graphics/text.js +123 -48
- package/dist/graphics/texture.js +48 -24
- package/dist/graphics/transform.js +29 -13
- package/dist/graphics/transformable.js +2 -1
- package/dist/graphics/vertex-array.js +40 -18
- package/dist/graphics/vertex-buffer.js +39 -19
- package/dist/graphics/vertex.js +6 -3
- package/dist/graphics/view.js +30 -14
- package/dist/index.d.ts +4 -4
- package/dist/internal/audio-codec-registry.js +12 -6
- package/dist/internal/audio-input-stream.js +2 -1
- package/dist/internal/audio-music-pump.js +58 -24
- package/dist/internal/audio-recorder-session.js +17 -7
- package/dist/internal/audio-worker-session.js +28 -10
- package/dist/internal/audio-worker.js +40 -21
- package/dist/internal/glsl-value.d.ts +3 -1
- package/dist/internal/glsl-value.js +18 -8
- package/dist/internal/graphics-state.js +29 -15
- package/dist/internal/input-stream.d.ts +3 -1
- package/dist/internal/input-stream.js +16 -7
- package/dist/internal/numeric-properties.js +2 -1
- package/dist/internal/render-states.js +2 -1
- package/dist/internal/scalar.js +22 -13
- package/dist/internal/shaped-glyph.d.ts +3 -1
- package/dist/internal/shaped-glyph.js +12 -4
- package/dist/internal/struct-view.d.ts +3 -1
- package/dist/internal/struct-view.js +3 -1
- package/dist/internal/transformable.js +2 -1
- package/dist/network/common.js +23 -11
- package/dist/network/dns.js +25 -17
- package/dist/network/ftp.js +43 -18
- package/dist/network/http.js +126 -56
- package/dist/network/ip-address.js +50 -25
- package/dist/network/packet.js +63 -25
- package/dist/network/sftp.js +175 -74
- package/dist/network/socket-selector.js +28 -14
- package/dist/network/socket.js +71 -30
- package/dist/network/tcp-listener.js +42 -19
- package/dist/network/tcp-socket.js +111 -53
- package/dist/network/tls-material.js +2 -1
- package/dist/network/udp-socket.js +68 -33
- package/dist/system/angle.js +2 -1
- package/dist/system/clock.js +4 -2
- package/dist/system/err.js +5 -2
- package/dist/system/file-input-stream.js +8 -4
- package/dist/system/input-stream.js +6 -3
- package/dist/system/operators.d.ts +1 -1
- package/dist/system/operators.js +90 -50
- package/dist/system/sleep.js +4 -2
- package/dist/system/time.js +12 -6
- package/dist/system/vector2.js +6 -7
- package/dist/system/vector3.js +11 -6
- package/dist/window/clipboard.js +2 -1
- package/dist/window/context.js +10 -5
- package/dist/window/cursor.js +2 -1
- package/dist/window/event.js +9 -5
- package/dist/window/mouse.js +4 -2
- package/dist/window/video-mode.js +2 -1
- package/dist/window/window.js +19 -12
- package/native/addon.cc +25 -12
- package/native/audio-binding.cc +266 -126
- package/native/audio-codec-binding.cc +147 -77
- package/native/audio-device-binding.cc +76 -49
- package/native/audio-file-binding.cc +116 -67
- package/native/audio-recorder-binding.cc +147 -98
- package/native/audio-recorder.h +1 -1
- package/native/audio-state.h +53 -30
- package/native/audio-stream-binding.cc +148 -94
- package/native/audio-stream.h +5 -4
- package/native/audio-worker-binding.cc +163 -81
- package/native/audio-worker.h +35 -19
- package/native/batch-drawable.cc +29 -16
- package/native/batch-drawable.h +11 -8
- package/native/context-binding.cc +40 -27
- package/native/context-settings.h +15 -8
- package/native/deferred-delete.cc +9 -6
- package/native/deferred-delete.h +7 -8
- package/native/error-stream-binding.cc +42 -28
- package/native/font-binding.cc +89 -48
- package/native/graphics-binding.cc +122 -72
- package/native/graphics-state.h +50 -36
- package/native/image-binding.cc +38 -24
- package/native/image-state.h +26 -18
- package/native/input-binding.cc +42 -27
- package/native/render-window-binding.cc +38 -23
- package/native/shader-binding.cc +115 -50
- package/native/shape-binding.cc +94 -49
- package/native/shape-state.h +18 -9
- package/native/shaped-glyph-storage.h +9 -5
- package/native/stream-binding.cc +143 -117
- package/native/system-binding.cc +17 -12
- package/native/text-binding.cc +68 -35
- package/native/text-state.h +25 -18
- package/native/texture-binding.cc +42 -33
- package/native/texture-resource.h +20 -12
- package/native/time-value.h +3 -1
- package/native/transformable-binding.cc +12 -6
- package/native/transformable-state.h +6 -6
- package/native/value-binding.h +46 -28
- package/native/value-layout.h +10 -10
- package/native/values-binding.cc +29 -23
- package/native/vertex-binding.cc +18 -12
- package/native/vertex-buffer-binding.cc +38 -24
- package/native/vertex-storage.h +2 -2
- package/native/view-data.h +4 -3
- package/native/window-binding.cc +75 -45
- package/native/window-event.h +20 -11
- package/native/window-owner.h +15 -12
- package/package.json +43 -50
- package/src/audio/effect-processor.ts +9 -3
- package/src/audio/input-sound-file.ts +108 -36
- package/src/audio/listener.ts +39 -13
- package/src/audio/music.ts +112 -47
- package/src/audio/output-sound-file.ts +40 -11
- package/src/audio/playback-device.ts +23 -8
- package/src/audio/sound-buffer-recorder.ts +35 -13
- package/src/audio/sound-buffer.ts +166 -58
- package/src/audio/sound-file-factory.ts +127 -49
- package/src/audio/sound-file-reader.ts +49 -15
- package/src/audio/sound-recorder.ts +100 -34
- package/src/audio/sound-source.ts +142 -45
- package/src/audio/sound-stream.ts +15 -5
- package/src/audio/sound.ts +12 -4
- package/src/audio/value.ts +89 -26
- package/src/graphics/blend-mode.ts +3 -1
- package/src/graphics/boolean-vector.ts +56 -26
- package/src/graphics/color.ts +3 -1
- package/src/graphics/convex-shape.ts +10 -3
- package/src/graphics/font.ts +171 -50
- package/src/graphics/glsl-matrix.ts +9 -3
- package/src/graphics/glsl.ts +81 -35
- package/src/graphics/glyph.ts +67 -26
- package/src/graphics/image.ts +119 -45
- package/src/graphics/rect.ts +56 -24
- package/src/graphics/render-states.ts +31 -14
- package/src/graphics/render-target.ts +197 -81
- package/src/graphics/render-texture.ts +36 -12
- package/src/graphics/render-window.ts +9 -3
- package/src/graphics/shader.ts +186 -61
- package/src/graphics/shape.ts +93 -35
- package/src/graphics/sprite.ts +64 -25
- package/src/graphics/stencil-mode.ts +12 -6
- package/src/graphics/swap.ts +3 -2
- package/src/graphics/text.ts +229 -74
- package/src/graphics/texture.ts +180 -61
- package/src/graphics/transform.ts +132 -47
- package/src/graphics/transformable.ts +3 -1
- package/src/graphics/vertex-array.ts +87 -35
- package/src/graphics/vertex-buffer.ts +97 -33
- package/src/graphics/vertex.ts +9 -3
- package/src/graphics/view.ts +59 -21
- package/src/index.ts +101 -23
- package/src/internal/audio-codec-registry.ts +18 -6
- package/src/internal/audio-input-stream.ts +6 -2
- package/src/internal/audio-music-pump.ts +116 -41
- package/src/internal/audio-native.ts +249 -96
- package/src/internal/audio-recorder-session.ts +68 -24
- package/src/internal/audio-worker-session.ts +65 -21
- package/src/internal/audio-worker.ts +85 -41
- package/src/internal/glsl-value.ts +26 -11
- package/src/internal/graphics-state.ts +57 -20
- package/src/internal/input-stream.ts +23 -10
- package/src/internal/native.ts +252 -99
- package/src/internal/numeric-properties.ts +2 -1
- package/src/internal/render-states.ts +3 -1
- package/src/internal/scalar.ts +33 -14
- package/src/internal/shaped-glyph.ts +25 -12
- package/src/internal/struct-view.ts +40 -13
- package/src/internal/transformable.ts +3 -1
- package/src/network/common.ts +35 -11
- package/src/network/dns.ts +95 -38
- package/src/network/ftp.ts +129 -47
- package/src/network/http.ts +232 -77
- package/src/network/ip-address.ts +118 -48
- package/src/network/packet.ts +161 -54
- package/src/network/sftp.ts +498 -168
- package/src/network/socket-selector.ts +66 -26
- package/src/network/socket.ts +133 -46
- package/src/network/tcp-listener.ts +78 -29
- package/src/network/tcp-socket.ts +240 -95
- package/src/network/tls-material.ts +6 -2
- package/src/network/udp-socket.ts +147 -53
- package/src/system/angle.ts +3 -1
- package/src/system/clock.ts +12 -4
- package/src/system/err.ts +5 -2
- package/src/system/file-input-stream.ts +12 -4
- package/src/system/input-stream.ts +9 -3
- package/src/system/operators.ts +290 -115
- package/src/system/sleep.ts +6 -2
- package/src/system/time.ts +18 -6
- package/src/system/timeout-with-predicate.ts +19 -8
- package/src/system/vector2.ts +101 -49
- package/src/system/vector3.ts +85 -36
- package/src/window/clipboard.ts +3 -1
- package/src/window/context.ts +15 -5
- package/src/window/cursor.ts +3 -1
- package/src/window/event.ts +26 -12
- package/src/window/mouse.ts +6 -2
- package/src/window/video-mode.ts +3 -1
- package/src/window/window.ts +119 -37
- package/test/native/audio-probes.cc +74 -36
- package/test/native/deferred-delete-probes.cc +17 -11
- package/test/native/drawable-probes.cc +70 -36
- package/test/native/exception-probes.cc +14 -9
- package/test/native/image-probes.cc +20 -10
- package/test/native/matrix-probes.cc +8 -4
- package/test/native/network-oracle.cc +17 -11
- package/test/native/render-texture-probes.cc +33 -24
- package/test/native/shader-probes.cc +9 -9
- package/test/native/shape-probes.cc +37 -23
- package/test/native/sprite-probes.cc +41 -25
- package/test/native/system-probes.cc +58 -35
- package/test/native/text-probes.cc +77 -44
- package/test/native/texture-probes.cc +43 -26
- package/test/native/time-probes.cc +18 -12
- package/test/native/transform-probes.cc +15 -10
- package/test/native/transformable-probes.cc +23 -17
- package/test/native/value-oracle.h +9 -4
- package/test/native/value-probes.cc +31 -23
- package/test/native/vertex-array-probes.cc +22 -14
- package/test/native/vertex-buffer-probes.cc +28 -17
- package/test/native/view-probes.cc +29 -17
- package/test/native/window-probes.cc +66 -33
- package/tools/ensure-sfml.cjs +9 -0
- package/tools/generate-network-constants.cjs +11 -6
- package/tools/generate-window-constants.cjs +31 -12
- package/docs/README.ja.md +0 -30
- package/docs/README.ko.md +0 -30
- package/docs/README.md +0 -30
- package/docs/README.zh-CN.md +0 -30
- package/docs/api.ja.md +0 -84
- package/docs/api.ko.md +0 -84
- package/docs/api.md +0 -81
- package/docs/api.zh-CN.md +0 -81
- package/docs/audio.ja.md +0 -249
- package/docs/audio.ko.md +0 -251
- package/docs/audio.md +0 -252
- package/docs/audio.zh-CN.md +0 -252
- package/docs/concepts.ja.md +0 -130
- package/docs/concepts.ko.md +0 -130
- package/docs/concepts.md +0 -131
- package/docs/concepts.zh-CN.md +0 -131
- package/docs/development.ja.md +0 -148
- package/docs/development.ko.md +0 -148
- package/docs/development.md +0 -150
- package/docs/development.zh-CN.md +0 -150
- package/docs/getting-started.ja.md +0 -154
- package/docs/getting-started.ko.md +0 -154
- package/docs/getting-started.md +0 -156
- package/docs/getting-started.zh-CN.md +0 -156
- package/docs/graphics.ja.md +0 -256
- package/docs/graphics.ko.md +0 -254
- package/docs/graphics.md +0 -255
- package/docs/graphics.zh-CN.md +0 -257
- package/docs/network.ja.md +0 -214
- package/docs/network.ko.md +0 -216
- package/docs/network.md +0 -218
- package/docs/network.zh-CN.md +0 -218
- package/docs/system.ja.md +0 -169
- package/docs/system.ko.md +0 -171
- package/docs/system.md +0 -173
- package/docs/system.zh-CN.md +0 -173
- package/docs/window.ja.md +0 -138
- package/docs/window.ko.md +0 -140
- package/docs/window.md +0 -141
- package/docs/window.zh-CN.md +0 -141
- package/native/exception-boundary.h +0 -97
- package/native/numeric-fields.h +0 -96
- package/native/shared-handle.h +0 -69
- package/test/tsconfig.json +0 -8
- package/tools/configure-lsp.cjs +0 -23
- package/tools/lib_downloader.cjs +0 -92
- package/tools/lib_downloader_urls.cjs +0 -23
package/docs/concepts.zh-CN.md
DELETED
|
@@ -1,131 +0,0 @@
|
|
|
1
|
-
# 核心概念
|
|
2
|
-
|
|
3
|
-
[English](concepts.md) · **简体中文** · [日本語](concepts.ja.md) · [한국어](concepts.ko.md)
|
|
4
|
-
|
|
5
|
-
> 使用 sfml.js 时,先区分值、资源和视图,再区分命令录制、提交与呈现。这些边界决定了复制、异步加载和绘制的行为。
|
|
6
|
-
|
|
7
|
-
[文档首页](README.zh-CN.md) · [API 导航](api.zh-CN.md)
|
|
8
|
-
|
|
9
|
-
## 值、资源与视图
|
|
10
|
-
|
|
11
|
-
向量、角度、颜色、矩形、顶点和矩阵等值类型从 JS TypedArray 存储开始,数学计算在 JavaScript 中完成,需要原生句柄时才包装同一块内存。`Time` 使用微秒 `bigint`。
|
|
12
|
-
|
|
13
|
-
Texture、Image、Sprite、Text 和音频对象等资源由 Native 管理。JS 包装对象及存活视图共同保活相关分配;资源释放遵循所属线程与底层依赖的生命周期。
|
|
14
|
-
|
|
15
|
-
```typescript
|
|
16
|
-
import { FloatRect, Vector2f } from 'sfml.js';
|
|
17
|
-
|
|
18
|
-
const rect = new FloatRect(new Vector2f(10, 20), new Vector2f(100, 80));
|
|
19
|
-
const member = rect.position;
|
|
20
|
-
member.x = 30; // 成员视图,修改 rect。
|
|
21
|
-
|
|
22
|
-
const copy = new Vector2f(member);
|
|
23
|
-
copy.x = 90; // 独立副本,不影响 rect。
|
|
24
|
-
|
|
25
|
-
rect.position = new Vector2f(5, 6); // 按值复制,member 仍指向 rect 的成员。
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
普通 JS 赋值仍是引用赋值。需要独立值时使用复制构造;资源的复制规则按类区分,例如 `new Texture(texture)` 复制 GPU 内容,`new Sprite(sprite)` 复制精灵属性但共用纹理。
|
|
29
|
-
|
|
30
|
-
不要仅凭 `get...()` 判断返回值是否独立:
|
|
31
|
-
|
|
32
|
-
| 读取方式 | 所有权与更新行为 |
|
|
33
|
-
| --- | --- |
|
|
34
|
-
| `sprite.getPosition()` | 独立向量;修改结果后需调用 `setPosition()` |
|
|
35
|
-
| `rect.position`、`vertex.color` | 父值的成员视图;写入直接修改父值 |
|
|
36
|
-
| `image.pixels` | 当前图像分配的可写 RGBA 视图 |
|
|
37
|
-
| `target.getTexture()` | RenderTexture 的稳定只读纹理视图 |
|
|
38
|
-
| `vertexArray.getVertex(i)` | 当前顶点存储的成员;结构变化后应重新获取 |
|
|
39
|
-
| `soundBuffer.getSamples()` | 保活 PCM 分配的只读类型视图,空缓冲为 `undefined` |
|
|
40
|
-
|
|
41
|
-
Image 成功重载或 resize 后,旧像素视图继续保活旧分配,并不会自动改为新图像。VertexArray 扩容后旧成员也指向旧存储;在容量内缩小后重新扩大则可能复用槽位。
|
|
42
|
-
|
|
43
|
-
`ReadonlyValue`、`ReadonlyPixels`、`ReadonlySamples` 等约束主要通过 TypeScript 表达;不能把所有只读类型都理解为运行时冻结。需要修改只读数据时先复制,不要转移、分离或调整底层共享 buffer。
|
|
44
|
-
|
|
45
|
-
## 资源加载与 Promise
|
|
46
|
-
|
|
47
|
-
图片和纹理用 `loadFromFile/Memory/Stream()`,字体和音乐用 `openFromFile/Memory/Stream()`。这些入口返回 Promise:
|
|
48
|
-
|
|
49
|
-
```typescript
|
|
50
|
-
import { Texture } from 'sfml.js';
|
|
51
|
-
|
|
52
|
-
const texture = new Texture();
|
|
53
|
-
if (!await texture.loadFromFile('sprite.png')) {
|
|
54
|
-
throw new Error('Cannot decode sprite.png');
|
|
55
|
-
}
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
Image/Texture 文件读取和解码在后台执行;纹理最终 GPU 上传仍在调用线程同步完成。`new Texture(image)`、像素上传及 GPU 读回是同步操作。异步加载失败通常保留旧资源,普通 SFML 失败返回 `false` 或 `undefined`。
|
|
59
|
-
|
|
60
|
-
同一图片或纹理上的多个异步加载按完成顺序发布结果。需要确定覆盖顺序时逐次 `await`,不要依赖发起顺序。
|
|
61
|
-
|
|
62
|
-
输入内存的所有权因模块而异:
|
|
63
|
-
|
|
64
|
-
| 输入 | 调用方的责任 |
|
|
65
|
-
| --- | --- |
|
|
66
|
-
| Image/Texture 的编码字节 | 调用时建立快照,后续可修改原输入 |
|
|
67
|
-
| `MemoryInputStream` | 保留原字节引用;加载期间保持内容不变,独占游标 |
|
|
68
|
-
| Audio 异步读写 | Promise 完成前保持相关缓冲不变 |
|
|
69
|
-
| `Music.openFromMemory()` | 输入保持不变,直到关闭或重新打开 |
|
|
70
|
-
|
|
71
|
-
流与音频对象的具体契约见 [System](system.zh-CN.md#input-streams) 和 [Audio](audio.zh-CN.md)。
|
|
72
|
-
|
|
73
|
-
<a id="draw-snapshots"></a>
|
|
74
|
-
|
|
75
|
-
## 绘制快照
|
|
76
|
-
|
|
77
|
-
`target.draw()` 记录调用时的属性和状态。修改原对象后再绘制,会得到另一份快照:
|
|
78
|
-
|
|
79
|
-
```typescript
|
|
80
|
-
import {
|
|
81
|
-
Color, Image, RenderTexture, Sprite, Texture, Vector2f, Vector2u,
|
|
82
|
-
} from 'sfml.js';
|
|
83
|
-
|
|
84
|
-
const target = new RenderTexture(new Vector2u(64, 32));
|
|
85
|
-
const sprite = new Sprite(new Texture(
|
|
86
|
-
new Image(new Vector2u(16, 16), Color.White),
|
|
87
|
-
));
|
|
88
|
-
|
|
89
|
-
target.clear();
|
|
90
|
-
sprite.setPosition(new Vector2f(0, 0));
|
|
91
|
-
target.draw(sprite);
|
|
92
|
-
sprite.setPosition(new Vector2f(32, 0));
|
|
93
|
-
target.draw(sprite);
|
|
94
|
-
target.display();
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
最终画面包含两个方块。Sprite 属性、RenderStates、顶点数据和所需资源引用在录制时保存;随后更改纹理像素、几何或 Shader uniform 时,绑定先提交依赖旧状态的命令。
|
|
98
|
-
|
|
99
|
-
| 操作 | 含义 |
|
|
100
|
-
| --- | --- |
|
|
101
|
-
| `clear()`、`draw()`、`setView()` | 按顺序录制命令;队列满时可能提前提交 |
|
|
102
|
-
| `flush()` | 同步提交已有命令 |
|
|
103
|
-
| `RenderWindow.display()` | 提交并交换窗口缓冲 |
|
|
104
|
-
| `RenderTexture.display()` | 提交并更新可采样纹理 |
|
|
105
|
-
|
|
106
|
-
`flush()` 不能替代离屏目标的 `display()`。使用 RenderTexture 的新内容之前先 display;直接采样自身纹理或建立未提交目标间的循环依赖会被拒绝。
|
|
107
|
-
|
|
108
|
-
批处理减少 JS/C++ 边界调用,并不会自动把多个 Sprite 合并成一次 GPU 绘制。大量共享纹理的几何可组织为 VertexArray;静态几何可使用 VertexBuffer。
|
|
109
|
-
|
|
110
|
-
## Node.js 事件循环
|
|
111
|
-
|
|
112
|
-
窗口操作在主线程执行。逐帧使用 `pollEvent()` 或 `handleEvents()`,并通过 `setImmediate()` 安排下一帧。
|
|
113
|
-
|
|
114
|
-
`waitEvent()` 保留 SFML 的同步等待语义。`sleep()` 使用 Node 定时器,返回 Promise;等待期间事件循环继续运行。`display()` 为同步方法,可能受到帧率限制、垂直同步和驱动工作的影响。
|
|
115
|
-
|
|
116
|
-
网络 I/O 返回 Promise。`socket.setBlocking(true)` 表示 Promise 等待操作就绪,不会同步阻塞整个 Node 线程。
|
|
117
|
-
|
|
118
|
-
Audio Worker 使用有界共享 PCM 槽位,回调视图只在本次回调完成前有效。后台 Worker 不独自维持进程;播放期间保留窗口循环或显式等待。
|
|
119
|
-
|
|
120
|
-
## 错误与清理
|
|
121
|
-
|
|
122
|
-
| 结果 | 处理方式 |
|
|
123
|
-
| --- | --- |
|
|
124
|
-
| `false`/`undefined`、SocketStatus、协议响应 | 检查返回状态 |
|
|
125
|
-
| `TypeError`/`RangeError` | 修正参数类型或范围 |
|
|
126
|
-
| `SFMLError` | 处理绑定或底层资源运行失败 |
|
|
127
|
-
| 用户回调抛错 | 原始错误对象继续传播 |
|
|
128
|
-
|
|
129
|
-
SFML 诊断默认写入 stderr,可用 `setErrorOutput()` 路由;日志不是返回值检查的替代品。
|
|
130
|
-
|
|
131
|
-
窗口使用 `close()`,网络对象使用各自的关闭接口,文件流和音频 Worker 的异步清理需要 `await`。仅依赖垃圾回收无法保证文件完成写入、连接及时结束或录音队列排空。资源的关闭方式见对应模块文档。
|
package/docs/development.ja.md
DELETED
|
@@ -1,148 +0,0 @@
|
|
|
1
|
-
# 開発ガイド
|
|
2
|
-
|
|
3
|
-
[English](development.md) / [简体中文](development.zh-CN.md) / **日本語** / [한국어](development.ko.md)
|
|
4
|
-
|
|
5
|
-
> このガイドは、ソースコードの変更、ドキュメントの保守、リポジトリのテストを行うコントリビューター向けです。依存パッケージとして利用する場合は[クイックスタート](getting-started.ja.md)から読んでください。
|
|
6
|
-
|
|
7
|
-
[ドキュメントトップ](README.ja.md) · [API ナビゲーション](api.ja.md) · [サンプル一覧](../examples/README.ja.md)
|
|
8
|
-
|
|
9
|
-
<a id="get-the-source"></a>
|
|
10
|
-
## ソースコードの取得
|
|
11
|
-
|
|
12
|
-
Node.js、Python、C++20 ツールチェーンを用意します。プラットフォーム別のインストールコマンドは[必要な環境](getting-started.ja.md#requirements)を参照し、その後に以下を実行してください。
|
|
13
|
-
|
|
14
|
-
```sh
|
|
15
|
-
git clone https://github.com/XadillaX/node-sfml.git
|
|
16
|
-
cd node-sfml
|
|
17
|
-
npm ci
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
`install` はネイティブモジュールをコンパイルし、`prepare` は TypeScript の定数、JavaScript、型宣言ファイルを生成します。ビルドフックは最初に SFML 3.1.0 を確認してダウンロードします。npm の依存パッケージとしてインストールする場合は、公開パッケージ内の dist を使うため、インストール時にはネイティブ部分のコンパイルだけが必要です。
|
|
21
|
-
|
|
22
|
-
## ビルド
|
|
23
|
-
|
|
24
|
-
以下のコマンドはすべてリポジトリのルートで実行します。
|
|
25
|
-
|
|
26
|
-
| コマンド | 用途 |
|
|
27
|
-
| --- | --- |
|
|
28
|
-
| `npm run build` | ネイティブ部分と TypeScript をコンパイル |
|
|
29
|
-
| `npm run build:native` | ネイティブ部分をコンパイルし、clangd の設定を更新 |
|
|
30
|
-
| `npm run build:ts` | 定数を生成し、TypeScript をコンパイル |
|
|
31
|
-
| `npm run build:docs` | 4 言語のサイトと API リファレンスをビルド |
|
|
32
|
-
| `npm run build:reference` | TypeDoc API ドキュメントのみを生成 |
|
|
33
|
-
| `npm run docs:dev` | サイトの開発プレビューを起動 |
|
|
34
|
-
| `npm run docs:preview` | 本番用ビルドをローカルでプレビュー |
|
|
35
|
-
| `npm run lint` | ソースコード、ツール、テスト、サンプルを検査 |
|
|
36
|
-
| `npm run test:types` | TypeScript のインターフェースを検証 |
|
|
37
|
-
| `npm run test:runtime` | ランタイムテストを直列に実行。事前にビルドが必要 |
|
|
38
|
-
| `npm test` | lint、ビルド、型検査、ランタイムテストを順に実行 |
|
|
39
|
-
| `npm run test:ported` | 移植済みサンプルを検証し、成功と未対応を区別して報告 |
|
|
40
|
-
| `npm pack --dry-run` | npm パッケージのファイル一覧を確認 |
|
|
41
|
-
|
|
42
|
-
TypeScript だけを変更した場合は `npm run build:ts`、ネイティブ部分を変更した場合は `npm run build` を実行します。ランタイムテストは自動的に再ビルドしないため、実行前にビルド結果とソースコードが一致していることを確認してください。
|
|
43
|
-
|
|
44
|
-
<a id="testing"></a>
|
|
45
|
-
## テストと検証
|
|
46
|
-
|
|
47
|
-
```sh
|
|
48
|
-
npm test
|
|
49
|
-
npm run test:ported
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
`npm test` は lint、ネイティブ部分と TypeScript のビルド、型検査、ランタイムテストを実行します。test:ported は旧バージョンから移植したサンプルを別途検証し、成功と未対応を区別します。
|
|
53
|
-
|
|
54
|
-
ランタイムテストはファイル単位で直列に実行し、公開インターフェース、ネイティブ SFML との比較、実際に描画されたピクセル、非同期 I/O、スナップショット、ライフサイクルを検証します。型テストは `test/*.types.ts`、ランタイムテストは `test/*.test.cjs`、ネイティブ比較テストは `test/native/` にあります。
|
|
55
|
-
|
|
56
|
-
グラフィックスのテストにはディスプレイサーバーと OpenGL コンテキストが必要です。ディスプレイのない Linux 環境では、[Linux CI](../.github/workflows/node.js.yml)に従って Xvfb をインストールしてから実行します。
|
|
57
|
-
|
|
58
|
-
```sh
|
|
59
|
-
LIBGL_ALWAYS_SOFTWARE=1 \
|
|
60
|
-
xvfb-run -a -s "-screen 0 1280x1024x24 -noreset" npm run test:runtime
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
CI は Linux、macOS、Windows の Node.js 20/22 を対象としています。[Windows CI](../.github/workflows/node.js-windows.yml)は Mesa のソフトウェア OpenGL を使います。
|
|
64
|
-
|
|
65
|
-
CI はスピーカー、マイク、ジョイスティック、センサー、フルスクリーン切り替えなどの実機確認の代わりにはなりません。SFML の macOS バックエンドは Vulkan に対応しておらず、SuspendAwareClock.now は Android のみ対応しています。結果を報告する際は、実際に実行したプラットフォームとスキップした項目を明記してください。
|
|
66
|
-
|
|
67
|
-
## ドキュメントの保守
|
|
68
|
-
|
|
69
|
-
README はプロジェクトの紹介と最小限のサンプルを、`docs/` は目的別・モジュール別の使い方を、`examples/README.md` は実行可能な入口を提供します。完全なシグネチャはソースコメントから生成し、手書きのドキュメントで別の宣言を維持しないようにします。
|
|
70
|
-
|
|
71
|
-
- サンプルは公開パッケージ `sfml.js` をインポートします。リポジトリ相対パスを使うのは、リポジトリ内のデモスクリプトだけです。
|
|
72
|
-
- 完全なサンプルと前後の文脈に依存する断片を区別し、async 関数、素材、デバイスの要件を説明します。
|
|
73
|
-
- 読み込みの真偽値とネットワークのステータスを確認し、サンプル終了時には所有するリソースを閉じます。
|
|
74
|
-
- 公開された挙動を変更する場合は、JSDoc、対応するガイド、影響を受けるサンプルも更新します。
|
|
75
|
-
|
|
76
|
-
サイトの依存パッケージをインストールしてビルドします。
|
|
77
|
-
|
|
78
|
-
```sh
|
|
79
|
-
npm ci --prefix site
|
|
80
|
-
npm run build:docs
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
`site/` には VitePress のテーマとビルドスクリプトがあります。英語・中国語・日本語・韓国語のガイドと API リファレンスを生成します。TypeDoc は `/reference/`、`/zh/reference/`、`/ja/reference/`、`/ko/reference/` に配置され、サイト全体は `build/site/` に出力されます。元の Markdown を編集し、`npm run docs:dev` を再起動して生成内容を更新してください。テーマの変更はホットリロードに対応しています。
|
|
84
|
-
|
|
85
|
-
ドキュメントの生成にネイティブモジュールのコンパイルや読み込みは不要です。ドキュメント専用環境では、先に `npm ci --ignore-scripts` を実行できます。`npm run build:reference` は TypeDoc のみを `build/docs/` に生成します。`npm --prefix site test` はリンク変換と旧 URL のリダイレクトを検証し、本番ビルドではルート、アンカー、画像なども検査します。
|
|
86
|
-
|
|
87
|
-
[Publish Docs ワークフロー](../.github/workflows/publish-docs.yml)は `main` の更新時に実行され、手動実行にも対応しています。生成結果は `gh-pages` ブランチの `docs/` にコミットされ、同ブランチのルートファイルを保持し、既存の `CNAME`(`sfml.js.org`)を引き継ぎます。生成内容に変更がなければコミットをスキップします。
|
|
88
|
-
|
|
89
|
-
以前の TypeDoc のクラスやインターフェースの URL は、フラグメントを保持して対応する英語リファレンスに転送されます。API の言語切り替えでは、現在のページとメンバーのアンカーを保持します。単独ビルドの `build/docs/` には、`zh/`、`ja/`、`ko/` の翻訳サブディレクトリも生成されます。
|
|
90
|
-
|
|
91
|
-
JSDoc は英語を先に書き、続けて `@zh`、`@ja`、`@ko` の翻訳を記述します。各翻訳は対応する概要やブロックタグの直後に置きます。引数の翻訳は `@ja name - 説明` の形式を使います。識別子、コード例、リンクを維持してください。文章の翻訳が不足すると、ドキュメントのビルドは失敗します。
|
|
92
|
-
|
|
93
|
-
```ts
|
|
94
|
-
/**
|
|
95
|
-
* Read the elapsed time.
|
|
96
|
-
* @zh 读取经过的时间。
|
|
97
|
-
* @ja 経過時間を読み取ります。
|
|
98
|
-
* @ko 경과 시간을 읽습니다.
|
|
99
|
-
* @param unit - Time unit.
|
|
100
|
-
* @zh unit - 时间单位。
|
|
101
|
-
* @ja unit - 時間の単位。
|
|
102
|
-
* @ko unit - 시간 단위.
|
|
103
|
-
*/
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
自動生成される定数の説明は `tools/constant-docs.json` と `tools/constant-docs.cjs` のテンプレートで管理します。変更後は `npm run generate:window` と `npm run generate:network` を実行し、生成済みのコメントを直接編集しないでください。
|
|
107
|
-
|
|
108
|
-
## サンプルの実行
|
|
109
|
-
|
|
110
|
-
以下のコマンドはリポジトリのルートで実行します。
|
|
111
|
-
|
|
112
|
-
```sh
|
|
113
|
-
npm run demo:types -- --frames=120
|
|
114
|
-
npm run demo:window -- --frames=120
|
|
115
|
-
npm run demo:audio
|
|
116
|
-
npm run demo:network
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
サンプルの説明は [examples/README.md](../examples/README.ja.md)を参照してください。ビルド済みであれば、`node examples/<名称>.cjs`(`<名称>` はサンプル名)で直接実行できます。`--frames` に対応する入口ではフレーム数を制限できます。スクリーンショットの撮影方法もサンプル一覧に記載しています。
|
|
120
|
-
|
|
121
|
-
旧版の `drawAsync`/`displayAsync` を使う 2 つのサンプルは、未対応であることを明示的に報告します。詳細は[移植に関する説明](../examples/ported/README.ja.md)を参照してください。
|
|
122
|
-
|
|
123
|
-
## ソースコードと生成ファイル
|
|
124
|
-
|
|
125
|
-
| ディレクトリ | 内容 |
|
|
126
|
-
| --- | --- |
|
|
127
|
-
| `src/` | TypeScript の実装 |
|
|
128
|
-
| `native/` | C++ バインディング |
|
|
129
|
-
| `test/` | ランタイム、型、ネイティブ比較テスト |
|
|
130
|
-
| `tools/` | 定数ジェネレーター、ベンチマーク、テストツール |
|
|
131
|
-
| `docs/` | API と開発のドキュメント |
|
|
132
|
-
| `site/` | サイトのテーマ、多言語対応、検索、ビルドスクリプト |
|
|
133
|
-
|
|
134
|
-
`build/`、`dist/`、`node_modules/`、ダウンロード済みの SFML はすべて生成物です。ウィンドウとネットワークの定数は現在の SFML ヘッダーから生成されるため、`src/*/gen/constants.ts` を直接編集しないでください。
|
|
135
|
-
|
|
136
|
-
ネイティブのビルド後、`.clangd` が使用する `build/compile_commands.json` が自動生成されます。言語サービスの設定だけを更新する場合は `npm run configure:lsp` を実行してください。エディターに古い診断が表示され続ける場合は clangd を再起動します。
|
|
137
|
-
|
|
138
|
-
## 実装上の規約
|
|
139
|
-
|
|
140
|
-
値型は TypedArray を使って計算と共有ストレージを実現し、ネイティブリソースとそのビューがメモリの寿命を維持します。グラフィックスのリソースは所属するスレッドで破棄します。描画の記録はスナップショットのセマンティクスを維持し、後からプロパティを変更しても記録済みの結果が変わらないようにしてください。
|
|
141
|
-
|
|
142
|
-
関連する入口は `src/internal/lazy-value.ts`、`src/internal/graphics-state.ts`、`native/shared-handle.h`、`native/deferred-delete.h`、`native/batch-drawable.h` です。公開フィールドやメソッドを追加する際は、機能、引数、上流との対応関係を説明する JSDoc を追加してください。
|
|
143
|
-
|
|
144
|
-
ダウンローダー、インストールフック、プラットフォーム別ビルドは相互に関係しているため、変更時には対応するプラットフォームで検証が必要です。ダウンロード URL とアーキテクチャのマッピングは `tools/lib_downloader_urls.cjs`、キャッシュは `third_party/sfml/` にあります。
|
|
145
|
-
|
|
146
|
-
## 変更の提出
|
|
147
|
-
|
|
148
|
-
PR には具体的な挙動、実施した検証、未検証のプラットフォーム固有の処理経路を記載してください。ネイティブ部分の変更では影響を受けるネイティブ比較テストを実行し、ドキュメントのみの変更ではリンク、コードサンプル、TypeDoc のビルドを確認します。性能値には、マシン、Node.js/SFML のバージョン、シナリオ、測定方法を添えてください。
|
package/docs/development.ko.md
DELETED
|
@@ -1,148 +0,0 @@
|
|
|
1
|
-
# 개발 가이드
|
|
2
|
-
|
|
3
|
-
[English](development.md) / [简体中文](development.zh-CN.md) / [日本語](development.ja.md) / **한국어**
|
|
4
|
-
|
|
5
|
-
> 이 문서는 소스를 수정하고 문서를 유지 보수하며 저장소 테스트를 실행하는 기여자를 위한 안내입니다. 의존성으로 사용하는 경우에는 [빠른 시작](getting-started.ko.md)부터 읽으세요.
|
|
6
|
-
|
|
7
|
-
[문서 홈](README.ko.md) · [API 안내](api.ko.md) · [예제 목록](../examples/README.ko.md)
|
|
8
|
-
|
|
9
|
-
<a id="get-the-source"></a>
|
|
10
|
-
## 소스 가져오기
|
|
11
|
-
|
|
12
|
-
Node.js, Python, C++20 도구 체인을 준비하세요. 플랫폼별 설치 명령은 [설치 환경](getting-started.ko.md#requirements)을 참고한 뒤 다음을 실행합니다.
|
|
13
|
-
|
|
14
|
-
```sh
|
|
15
|
-
git clone https://github.com/XadillaX/node-sfml.git
|
|
16
|
-
cd node-sfml
|
|
17
|
-
npm ci
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
`install`은 네이티브 모듈을 컴파일하고, `prepare`는 TypeScript 상수, JavaScript, 선언 파일을 생성합니다. 빌드 훅은 먼저 SFML 3.1.0을 확인하고 다운로드합니다. npm 의존성으로 설치할 때는 배포 패키지의 dist를 사용하므로, 설치 단계에서는 네이티브 모듈만 컴파일하면 됩니다.
|
|
21
|
-
|
|
22
|
-
## 빌드
|
|
23
|
-
|
|
24
|
-
아래 명령은 모두 저장소 루트 디렉터리에서 실행합니다.
|
|
25
|
-
|
|
26
|
-
| 명령 | 용도 |
|
|
27
|
-
| --- | --- |
|
|
28
|
-
| `npm run build` | 네이티브 모듈과 TypeScript 컴파일 |
|
|
29
|
-
| `npm run build:native` | 네이티브 모듈 컴파일 및 clangd 설정 업데이트 |
|
|
30
|
-
| `npm run build:ts` | 상수 생성 및 TypeScript 컴파일 |
|
|
31
|
-
| `npm run build:docs` | 4개 언어 사이트와 API 레퍼런스 빌드 |
|
|
32
|
-
| `npm run build:reference` | TypeDoc API 문서만 생성 |
|
|
33
|
-
| `npm run docs:dev` | 사이트 개발 미리 보기 시작 |
|
|
34
|
-
| `npm run docs:preview` | 프로덕션 빌드를 로컬에서 미리 보기 |
|
|
35
|
-
| `npm run lint` | 소스, 도구, 테스트, 예제 검사 |
|
|
36
|
-
| `npm run test:types` | TypeScript 인터페이스 검증 |
|
|
37
|
-
| `npm run test:runtime` | 런타임 테스트를 직렬 실행. 사전 빌드 필요 |
|
|
38
|
-
| `npm test` | lint, 빌드, 타입 검사, 런타임 테스트를 순서대로 실행 |
|
|
39
|
-
| `npm run test:ported` | 포팅된 예제를 검증하고 통과와 미지원을 구분해 보고 |
|
|
40
|
-
| `npm pack --dry-run` | npm 패키지 파일 목록 확인 |
|
|
41
|
-
|
|
42
|
-
TypeScript만 수정했다면 `npm run build:ts`를 실행할 수 있습니다. 네이티브 코드를 수정했다면 `npm run build`를 실행하세요. 런타임 테스트는 자동으로 다시 빌드하지 않으므로, 실행 전에 빌드 결과가 소스와 일치하는지 확인해야 합니다.
|
|
43
|
-
|
|
44
|
-
<a id="testing"></a>
|
|
45
|
-
## 테스트와 검증
|
|
46
|
-
|
|
47
|
-
```sh
|
|
48
|
-
npm test
|
|
49
|
-
npm run test:ported
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
`npm test`는 lint, 네이티브 및 TypeScript 빌드, 타입 검사, 런타임 테스트를 실행합니다. test:ported는 이전 버전에서 포팅한 예제를 별도로 검증하며, 통과와 미지원을 구분합니다.
|
|
53
|
-
|
|
54
|
-
런타임 테스트는 파일별로 직렬 실행되며 공개 인터페이스, 네이티브 SFML 대조, 실제 렌더링 픽셀, 비동기 I/O, 스냅샷, 수명 주기를 검증합니다. 타입 테스트는 `test/*.types.ts`, 런타임 테스트는 `test/*.test.cjs`, 네이티브 대조 테스트는 `test/native/`에 있습니다.
|
|
55
|
-
|
|
56
|
-
그래픽 테스트에는 디스플레이 서버와 OpenGL 컨텍스트가 필요합니다. 디스플레이가 없는 Linux 환경에서는 [Linux CI](../.github/workflows/node.js.yml)에 따라 Xvfb를 설치한 뒤 실행하세요.
|
|
57
|
-
|
|
58
|
-
```sh
|
|
59
|
-
LIBGL_ALWAYS_SOFTWARE=1 \
|
|
60
|
-
xvfb-run -a -s "-screen 0 1280x1024x24 -noreset" npm run test:runtime
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
CI 구성은 Linux, macOS, Windows의 Node.js 20/22를 포함하며, [Windows CI](../.github/workflows/node.js-windows.yml)는 Mesa 소프트웨어 OpenGL을 사용합니다.
|
|
64
|
-
|
|
65
|
-
CI는 스피커, 마이크, 조이스틱, 센서, 전체 화면 전환 등의 장치 검증을 대신할 수 없습니다. SFML의 macOS 백엔드는 Vulkan을 지원하지 않으며, SuspendAwareClock.now는 Android만 지원합니다. 결과를 보고할 때는 실제 실행 플랫폼과 건너뛴 항목을 명시하세요.
|
|
66
|
-
|
|
67
|
-
## 문서 유지 보수
|
|
68
|
-
|
|
69
|
-
README는 프로젝트 소개와 최소 예제를 담당하고, `docs/`는 작업 및 모듈별 사용법을 설명하며, `examples/README.md`는 실행 가능한 진입점을 제공합니다. 전체 시그니처는 소스 주석에서 생성하므로, 직접 작성한 문서에서 선언을 중복 관리하지 마세요.
|
|
70
|
-
|
|
71
|
-
- 예제는 공개 패키지 `sfml.js`를 가져옵니다. 저장소 데모 스크립트에서만 저장소 상대 경로를 사용합니다.
|
|
72
|
-
- 완전한 예제와 주변 코드가 필요한 조각을 구분하고, async 함수, 리소스 파일, 장치 요구 사항을 설명합니다.
|
|
73
|
-
- 로딩 불리언 값과 네트워크 상태를 확인하고, 예제가 끝나면 소유한 리소스를 닫습니다.
|
|
74
|
-
- 공개 동작을 변경하면 JSDoc, 해당 가이드, 영향을 받는 예제도 함께 유지 보수합니다.
|
|
75
|
-
|
|
76
|
-
사이트 의존성을 설치하고 빌드합니다.
|
|
77
|
-
|
|
78
|
-
```sh
|
|
79
|
-
npm ci --prefix site
|
|
80
|
-
npm run build:docs
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
`site/`에는 VitePress 테마와 빌드 스크립트가 있습니다. 영어, 중국어, 일본어, 한국어 가이드와 API 레퍼런스를 생성합니다. TypeDoc은 `/reference/`, `/zh/reference/`, `/ja/reference/`, `/ko/reference/`에 배치하며 전체 사이트는 `build/site/`에 출력합니다. 원본 Markdown을 편집하고 `npm run docs:dev`를 다시 시작하여 생성 내용을 갱신하세요. 테마 변경에는 핫 리로드가 적용됩니다.
|
|
84
|
-
|
|
85
|
-
문서 생성에는 네이티브 모듈을 컴파일하거나 로드할 필요가 없습니다. 문서 전용 환경에서는 먼저 `npm ci --ignore-scripts`를 실행할 수 있습니다. `npm run build:reference`는 TypeDoc만 `build/docs/`에 생성합니다. `npm --prefix site test`는 링크 변환과 이전 URL 리다이렉트를 검증하며, 프로덕션 빌드에서는 경로, 앵커, 리소스도 검사합니다.
|
|
86
|
-
|
|
87
|
-
[Publish Docs 워크플로](../.github/workflows/publish-docs.yml)는 `main`이 업데이트될 때 실행되며, 수동 실행도 지원합니다. 생성 결과는 `gh-pages` 브랜치의 `docs/`에 커밋하고, 해당 브랜치의 루트 파일은 보존하며, 기존 `CNAME`(`sfml.js.org`)을 유지합니다. 생성 내용에 변화가 없으면 커밋을 건너뜁니다.
|
|
88
|
-
|
|
89
|
-
이전 TypeDoc 클래스와 인터페이스 URL은 프래그먼트를 유지하며 해당 영어 레퍼런스 페이지로 이동합니다. API 언어를 전환해도 현재 페이지와 멤버 앵커가 유지됩니다. 단독 빌드의 `build/docs/`에도 번역을 위한 `zh/`, `ja/`, `ko/` 하위 디렉터리가 생성됩니다.
|
|
90
|
-
|
|
91
|
-
JSDoc은 영어를 먼저 쓰고 `@zh`, `@ja`, `@ko` 번역을 이어서 작성합니다. 번역은 해당 요약이나 블록 태그 바로 뒤에 둡니다. 매개변수 번역은 `@ko name - 설명` 형식을 사용합니다. 식별자, 예제 코드, 링크를 유지하세요. 설명 번역이 누락되면 문서 빌드가 실패합니다.
|
|
92
|
-
|
|
93
|
-
```ts
|
|
94
|
-
/**
|
|
95
|
-
* Read the elapsed time.
|
|
96
|
-
* @zh 读取经过的时间。
|
|
97
|
-
* @ja 経過時間を読み取ります。
|
|
98
|
-
* @ko 경과 시간을 읽습니다.
|
|
99
|
-
* @param unit - Time unit.
|
|
100
|
-
* @zh unit - 时间单位。
|
|
101
|
-
* @ja unit - 時間の単位。
|
|
102
|
-
* @ko unit - 시간 단위.
|
|
103
|
-
*/
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
자동 생성되는 상수 설명은 `tools/constant-docs.json`과 `tools/constant-docs.cjs`의 템플릿에서 관리합니다. 수정 후 `npm run generate:window`와 `npm run generate:network`를 실행하고 생성된 주석은 직접 편집하지 마세요.
|
|
107
|
-
|
|
108
|
-
## 예제 실행
|
|
109
|
-
|
|
110
|
-
아래 명령은 저장소 루트 디렉터리에서 실행합니다.
|
|
111
|
-
|
|
112
|
-
```sh
|
|
113
|
-
npm run demo:types -- --frames=120
|
|
114
|
-
npm run demo:window -- --frames=120
|
|
115
|
-
npm run demo:audio
|
|
116
|
-
npm run demo:network
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
예제 설명은 [examples/README.md](../examples/README.ko.md)를 참고하세요. 빌드된 상태라면 `node examples/<이름>.cjs`를 직접 실행할 수 있습니다. `--frames`를 지원하는 진입점에서는 프레임 수를 제한할 수 있으며, 스크린샷 방법도 예제 목록에 설명되어 있습니다.
|
|
120
|
-
|
|
121
|
-
이전 버전의 `drawAsync`/`displayAsync` 예제 두 개는 미지원 상태를 명시적으로 보고합니다. 자세한 내용은 [포팅 안내](../examples/ported/README.ko.md)를 참고하세요.
|
|
122
|
-
|
|
123
|
-
## 소스와 생성 파일
|
|
124
|
-
|
|
125
|
-
| 디렉터리 | 내용 |
|
|
126
|
-
| --- | --- |
|
|
127
|
-
| `src/` | TypeScript 구현 |
|
|
128
|
-
| `native/` | C++ 바인딩 |
|
|
129
|
-
| `test/` | 런타임, 타입, 네이티브 대조 테스트 |
|
|
130
|
-
| `tools/` | 상수 생성기, 벤치마크, 테스트 도구 |
|
|
131
|
-
| `docs/` | API 및 개발 문서 |
|
|
132
|
-
| `site/` | 사이트 테마, 다국어 지원, 검색, 빌드 스크립트 |
|
|
133
|
-
|
|
134
|
-
`build/`, `dist/`, `node_modules/`, 다운로드한 SFML은 모두 생성된 내용입니다. 창 및 네트워크 상수는 현재 SFML 헤더에서 생성하므로 `src/*/gen/constants.ts`를 직접 편집하지 마세요.
|
|
135
|
-
|
|
136
|
-
네이티브 빌드 후에는 `.clangd`에서 사용할 `build/compile_commands.json`이 자동 생성됩니다. 언어 서버 설정만 업데이트하려면 `npm run configure:lsp`를 실행하세요. 편집기에 이전 진단이 남아 있으면 clangd를 다시 시작합니다.
|
|
137
|
-
|
|
138
|
-
## 구현 규칙
|
|
139
|
-
|
|
140
|
-
값 타입은 TypedArray로 계산하고 저장소를 공유하며, 네이티브 리소스와 해당 뷰가 메모리 수명을 유지합니다. 그래픽 리소스는 소유 스레드에서 소멸해야 합니다. 그리기 기록은 스냅샷 의미를 유지해야 하며, 이후의 속성 변경이 이미 기록한 결과를 바꾸어서는 안 됩니다.
|
|
141
|
-
|
|
142
|
-
관련 진입점은 `src/internal/lazy-value.ts`, `src/internal/graphics-state.ts`, `native/shared-handle.h`, `native/deferred-delete.h`, `native/batch-drawable.h`입니다. 공개 필드나 메서드를 추가할 때는 기능, 매개변수, 업스트림 대응 관계를 설명하는 JSDoc을 작성하세요.
|
|
143
|
-
|
|
144
|
-
다운로더, 설치 훅, 플랫폼 빌드는 서로 연결되어 있으므로 수정 시 해당 플랫폼에서 검증해야 합니다. 다운로드 URL과 아키텍처 매핑은 `tools/lib_downloader_urls.cjs`에, 캐시는 `third_party/sfml/`에 있습니다.
|
|
145
|
-
|
|
146
|
-
## 변경 제출
|
|
147
|
-
|
|
148
|
-
PR에는 구체적인 동작, 관련 검증, 아직 검증하지 않은 플랫폼 경로를 설명하세요. 네이티브 변경 시에는 영향을 받는 네이티브 대조 테스트를 실행합니다. 문서만 변경한 경우에는 링크, 코드 예제, TypeDoc 빌드를 확인합니다. 성능 수치에는 장비, Node.js/SFML 버전, 시나리오, 측정 방법을 함께 기재해야 합니다.
|
package/docs/development.md
DELETED
|
@@ -1,150 +0,0 @@
|
|
|
1
|
-
# Development Guide
|
|
2
|
-
|
|
3
|
-
**English** · [简体中文](development.zh-CN.md) · [日本語](development.ja.md) · [한국어](development.ko.md)
|
|
4
|
-
|
|
5
|
-
> This guide is for contributors changing source code, maintaining documentation or running repository tests. To use sfml.js as a dependency, start with [Quick start](getting-started.md).
|
|
6
|
-
|
|
7
|
-
[Documentation](README.md) · [API guide](api.md) · [Examples](../examples/README.md)
|
|
8
|
-
|
|
9
|
-
<a id="get-the-source"></a>
|
|
10
|
-
|
|
11
|
-
## Get the source
|
|
12
|
-
|
|
13
|
-
Prepare Node.js, Python and a C++20 toolchain; see [requirements](getting-started.md#requirements) for platform installation commands. Then run:
|
|
14
|
-
|
|
15
|
-
```sh
|
|
16
|
-
git clone https://github.com/XadillaX/node-sfml.git
|
|
17
|
-
cd node-sfml
|
|
18
|
-
npm ci
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
`install` compiles the native module; `prepare` generates TypeScript constants, JavaScript and declaration files. Build hooks first check for and download SFML 3.1.0. When installed as an npm dependency, the package uses the published dist, so only the native module needs compiling during installation.
|
|
22
|
-
|
|
23
|
-
## Building
|
|
24
|
-
|
|
25
|
-
Run these commands from the repository root:
|
|
26
|
-
|
|
27
|
-
| Command | Purpose |
|
|
28
|
-
| --- | --- |
|
|
29
|
-
| `npm run build` | Compile native code and TypeScript |
|
|
30
|
-
| `npm run build:native` | Compile native code and update clangd configuration |
|
|
31
|
-
| `npm run build:ts` | Generate constants and compile TypeScript |
|
|
32
|
-
| `npm run build:docs` | Build the four-language website and generated API reference |
|
|
33
|
-
| `npm run build:reference` | Generate TypeDoc API documentation only |
|
|
34
|
-
| `npm run docs:dev` | Preview the website during development |
|
|
35
|
-
| `npm run docs:preview` | Serve the production website build locally |
|
|
36
|
-
| `npm run lint` | Check source, tools, tests and examples |
|
|
37
|
-
| `npm run test:types` | Validate TypeScript APIs |
|
|
38
|
-
| `npm run test:runtime` | Run runtime tests serially; requires a prior build |
|
|
39
|
-
| `npm test` | Run lint, build, type checks and runtime tests in sequence |
|
|
40
|
-
| `npm run test:ported` | Validate ported examples, reporting passes and unsupported cases separately |
|
|
41
|
-
| `npm pack --dry-run` | Inspect the npm package file list |
|
|
42
|
-
|
|
43
|
-
For TypeScript-only changes, run `npm run build:ts`; after native changes, run `npm run build`. Runtime tests do not rebuild automatically, so ensure the build matches the source before running them.
|
|
44
|
-
|
|
45
|
-
<a id="testing"></a>
|
|
46
|
-
|
|
47
|
-
## Testing and verification
|
|
48
|
-
|
|
49
|
-
```sh
|
|
50
|
-
npm test
|
|
51
|
-
npm run test:ported
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
`npm test` runs lint, native and TypeScript builds, type checks and runtime tests. test:ported separately validates ported legacy examples, distinguishing passing cases from unsupported ones.
|
|
55
|
-
|
|
56
|
-
Runtime tests run serially by file, covering public APIs, comparisons with native SFML, actual rendered pixels, asynchronous I/O, snapshots and lifetimes. Type tests are in `test/*.types.ts`, runtime tests in `test/*.test.cjs`, and native comparisons in `test/native/`.
|
|
57
|
-
|
|
58
|
-
Graphics tests require a display server and an OpenGL context. For headless Linux, install Xvfb as shown in [Linux CI](../.github/workflows/node.js.yml), then run:
|
|
59
|
-
|
|
60
|
-
```sh
|
|
61
|
-
LIBGL_ALWAYS_SOFTWARE=1 \
|
|
62
|
-
xvfb-run -a -s "-screen 0 1280x1024x24 -noreset" npm run test:runtime
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
CI is configured for Node.js 20/22 on Linux, macOS and Windows; [Windows CI](../.github/workflows/node.js-windows.yml) uses Mesa software OpenGL.
|
|
66
|
-
|
|
67
|
-
CI does not replace device testing for speakers, microphones, joysticks, sensors or fullscreen switching. SFML's macOS backend does not support Vulkan, and SuspendAwareClock.now supports only Android. State the actual platform and skipped cases when reporting results.
|
|
68
|
-
|
|
69
|
-
## Maintaining documentation
|
|
70
|
-
|
|
71
|
-
The README introduces the project and provides a minimal example; `docs/` explains usage by task and module; `examples/README.md` provides runnable entry points. Generate complete signatures from source comments instead of maintaining a duplicate set of declarations in handwritten documentation.
|
|
72
|
-
|
|
73
|
-
- Examples import the public `sfml.js` package; only repository demo scripts use repository-relative paths.
|
|
74
|
-
- Distinguish complete examples from context-dependent snippets, and state requirements for async functions, assets and devices.
|
|
75
|
-
- Check loading booleans and network statuses, and close owned resources when examples end.
|
|
76
|
-
- When changing public behavior, update JSDoc, the relevant guides and affected examples together.
|
|
77
|
-
|
|
78
|
-
Install the website dependencies, then build the website:
|
|
79
|
-
|
|
80
|
-
```sh
|
|
81
|
-
npm ci --prefix site
|
|
82
|
-
npm run build:docs
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
`site/` contains the VitePress theme and build scripts. The build prepares English, Chinese, Japanese and Korean guides and API references. TypeDoc lives at `/reference/`, `/zh/reference/`, `/ja/reference/` and `/ko/reference/`; the complete website is written to `build/site/`. Edit the original Markdown files, then restart `npm run docs:dev` to refresh prepared content. Theme changes support hot reload.
|
|
86
|
-
|
|
87
|
-
Documentation generation does not require compiling or loading the native module; documentation-only environments can first run `npm ci --ignore-scripts`. `npm run build:reference` generates standalone TypeDoc in `build/docs/`, with translations in its `zh/`, `ja/` and `ko/` subdirectories. `npm --prefix site test` checks localization, link conversion and legacy redirects; the production build also validates generated routes, anchors and assets.
|
|
88
|
-
|
|
89
|
-
The [Publish Docs workflow](../.github/workflows/publish-docs.yml) runs on updates to `main` and also supports manual dispatch. Generated output is committed to `docs/` on the `gh-pages` branch, preserving files at that branch's root and its existing `CNAME` (`sfml.js.org`). It skips the commit when generated content is unchanged.
|
|
90
|
-
|
|
91
|
-
Legacy TypeDoc class and interface URLs redirect to the corresponding English reference page, preserving fragment links. The API language selector preserves the current page and member anchor.
|
|
92
|
-
|
|
93
|
-
Write JSDoc in English first, followed by `@zh`, `@ja` and `@ko` translations. Place each translation immediately after its summary or block tag. Parameter translations use `@zh name - description` (likewise for Japanese and Korean). Keep identifiers, code examples and links intact. Missing prose translations fail the documentation build.
|
|
94
|
-
|
|
95
|
-
```ts
|
|
96
|
-
/**
|
|
97
|
-
* Read the elapsed time.
|
|
98
|
-
* @zh 读取经过的时间。
|
|
99
|
-
* @ja 経過時間を読み取ります。
|
|
100
|
-
* @ko 경과 시간을 읽습니다.
|
|
101
|
-
* @param unit - Time unit.
|
|
102
|
-
* @zh unit - 时间单位。
|
|
103
|
-
* @ja unit - 時間の単位。
|
|
104
|
-
* @ko unit - 시간 단위.
|
|
105
|
-
*/
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
Generated constant descriptions are maintained in `tools/constant-docs.json` and the templates in `tools/constant-docs.cjs`. Run `npm run generate:window` and `npm run generate:network` after editing them; do not edit generated comments directly.
|
|
109
|
-
|
|
110
|
-
## Running examples
|
|
111
|
-
|
|
112
|
-
Run these commands from the repository root:
|
|
113
|
-
|
|
114
|
-
```sh
|
|
115
|
-
npm run demo:types -- --frames=120
|
|
116
|
-
npm run demo:window -- --frames=120
|
|
117
|
-
npm run demo:audio
|
|
118
|
-
npm run demo:network
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
See [examples/README.md](../examples/README.md) for descriptions. After building, run `node examples/<name>.cjs` directly. Entry points supporting `--frames` can limit the frame count; the examples guide also explains how to capture screenshots.
|
|
122
|
-
|
|
123
|
-
The two legacy `drawAsync`/`displayAsync` examples explicitly report that they are unsupported; see the [ported examples](../examples/ported/README.md).
|
|
124
|
-
|
|
125
|
-
## Source and generated files
|
|
126
|
-
|
|
127
|
-
| Directory | Contents |
|
|
128
|
-
| --- | --- |
|
|
129
|
-
| `src/` | TypeScript implementation |
|
|
130
|
-
| `native/` | C++ bindings |
|
|
131
|
-
| `test/` | Runtime, type and native comparison tests |
|
|
132
|
-
| `tools/` | Constant generators, benchmarks and test tools |
|
|
133
|
-
| `docs/` | API and development documentation |
|
|
134
|
-
| `site/` | Website theme, localization, search and build scripts |
|
|
135
|
-
|
|
136
|
-
`build/`, `dist/`, `node_modules/` and downloaded SFML libraries are generated content. Window and network constants are generated from the current SFML headers; do not edit `src/*/gen/constants.ts` directly.
|
|
137
|
-
|
|
138
|
-
Native builds automatically generate `build/compile_commands.json` for `.clangd`. To update only the language server configuration, run `npm run configure:lsp`; restart clangd if the editor still shows stale diagnostics.
|
|
139
|
-
|
|
140
|
-
## Implementation conventions
|
|
141
|
-
|
|
142
|
-
Value types use TypedArray for calculations and shared storage; native resources and their views keep memory alive. Graphics resources are destroyed on their owning thread. Recorded draws must preserve snapshot semantics: later property changes must not alter previously recorded results.
|
|
143
|
-
|
|
144
|
-
Relevant entry points include `src/internal/lazy-value.ts`, `src/internal/graphics-state.ts`, `native/shared-handle.h`, `native/deferred-delete.h` and `native/batch-drawable.h`. Add JSDoc describing behavior, parameters and upstream counterparts when adding public fields or methods.
|
|
145
|
-
|
|
146
|
-
The downloader, installation hooks and platform builds are interconnected; validate the corresponding platforms when changing them. Download URLs and architecture mappings are in `tools/lib_downloader_urls.cjs`, and the cache is in `third_party/sfml/`.
|
|
147
|
-
|
|
148
|
-
## Submitting changes
|
|
149
|
-
|
|
150
|
-
Describe the specific behavior, relevant verification and unverified platform paths in the PR. Run affected native comparison tests for native changes; check links, code examples and the TypeDoc build for documentation-only changes. Include the machine, Node.js/SFML versions, scenario and measurement method with performance figures.
|