sfml.js 1.0.0 → 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.
Files changed (313) hide show
  1. package/README.ja.md +10 -9
  2. package/README.ko.md +10 -9
  3. package/README.md +10 -9
  4. package/README.zh-CN.md +10 -9
  5. package/binding.gyp +23 -16
  6. package/dist/audio/effect-processor.js +9 -3
  7. package/dist/audio/input-sound-file.js +41 -15
  8. package/dist/audio/listener.js +33 -11
  9. package/dist/audio/music.js +41 -18
  10. package/dist/audio/output-sound-file.js +4 -2
  11. package/dist/audio/playback-device.js +11 -3
  12. package/dist/audio/sound-buffer-recorder.js +8 -5
  13. package/dist/audio/sound-buffer.js +40 -17
  14. package/dist/audio/sound-file-factory.js +21 -9
  15. package/dist/audio/sound-file-reader.js +21 -7
  16. package/dist/audio/sound-recorder.js +36 -15
  17. package/dist/audio/sound-source.js +117 -40
  18. package/dist/audio/sound-stream.js +14 -5
  19. package/dist/audio/sound.js +9 -4
  20. package/dist/audio/value.js +42 -16
  21. package/dist/graphics/blend-mode.js +2 -1
  22. package/dist/graphics/boolean-vector.d.ts +1 -2
  23. package/dist/graphics/boolean-vector.js +19 -9
  24. package/dist/graphics/color.js +2 -1
  25. package/dist/graphics/convex-shape.js +7 -3
  26. package/dist/graphics/font.js +52 -23
  27. package/dist/graphics/glsl-matrix.js +8 -3
  28. package/dist/graphics/glsl.js +47 -16
  29. package/dist/graphics/glyph.js +27 -10
  30. package/dist/graphics/image.js +30 -14
  31. package/dist/graphics/rect.js +15 -8
  32. package/dist/graphics/render-states.js +18 -9
  33. package/dist/graphics/render-target.js +49 -23
  34. package/dist/graphics/render-texture.js +24 -12
  35. package/dist/graphics/render-window.js +6 -3
  36. package/dist/graphics/shader.js +67 -32
  37. package/dist/graphics/shape.js +25 -13
  38. package/dist/graphics/sprite.js +19 -9
  39. package/dist/graphics/stencil-mode.js +10 -6
  40. package/dist/graphics/swap.js +2 -1
  41. package/dist/graphics/text.js +123 -48
  42. package/dist/graphics/texture.js +48 -24
  43. package/dist/graphics/transform.js +29 -13
  44. package/dist/graphics/transformable.js +2 -1
  45. package/dist/graphics/vertex-array.js +40 -18
  46. package/dist/graphics/vertex-buffer.js +39 -19
  47. package/dist/graphics/vertex.js +6 -3
  48. package/dist/graphics/view.js +30 -14
  49. package/dist/index.d.ts +4 -4
  50. package/dist/internal/audio-codec-registry.js +12 -6
  51. package/dist/internal/audio-input-stream.js +2 -1
  52. package/dist/internal/audio-music-pump.js +58 -24
  53. package/dist/internal/audio-recorder-session.js +17 -7
  54. package/dist/internal/audio-worker-session.js +28 -10
  55. package/dist/internal/audio-worker.js +40 -21
  56. package/dist/internal/glsl-value.d.ts +3 -1
  57. package/dist/internal/glsl-value.js +18 -8
  58. package/dist/internal/graphics-state.js +29 -15
  59. package/dist/internal/input-stream.d.ts +3 -1
  60. package/dist/internal/input-stream.js +16 -7
  61. package/dist/internal/numeric-properties.js +2 -1
  62. package/dist/internal/render-states.js +2 -1
  63. package/dist/internal/scalar.js +22 -13
  64. package/dist/internal/shaped-glyph.d.ts +3 -1
  65. package/dist/internal/shaped-glyph.js +12 -4
  66. package/dist/internal/struct-view.d.ts +3 -1
  67. package/dist/internal/struct-view.js +3 -1
  68. package/dist/internal/transformable.js +2 -1
  69. package/dist/network/common.js +23 -11
  70. package/dist/network/dns.js +25 -17
  71. package/dist/network/ftp.js +43 -18
  72. package/dist/network/http.js +126 -56
  73. package/dist/network/ip-address.js +50 -25
  74. package/dist/network/packet.js +63 -25
  75. package/dist/network/sftp.js +175 -74
  76. package/dist/network/socket-selector.js +28 -14
  77. package/dist/network/socket.js +71 -30
  78. package/dist/network/tcp-listener.js +42 -19
  79. package/dist/network/tcp-socket.js +111 -53
  80. package/dist/network/tls-material.js +2 -1
  81. package/dist/network/udp-socket.js +68 -33
  82. package/dist/system/angle.js +2 -1
  83. package/dist/system/clock.js +4 -2
  84. package/dist/system/err.js +5 -2
  85. package/dist/system/file-input-stream.js +8 -4
  86. package/dist/system/input-stream.js +6 -3
  87. package/dist/system/operators.d.ts +1 -1
  88. package/dist/system/operators.js +90 -50
  89. package/dist/system/sleep.js +4 -2
  90. package/dist/system/time.js +12 -6
  91. package/dist/system/vector2.js +6 -7
  92. package/dist/system/vector3.js +11 -6
  93. package/dist/window/clipboard.js +2 -1
  94. package/dist/window/context.js +10 -5
  95. package/dist/window/cursor.js +2 -1
  96. package/dist/window/event.js +9 -5
  97. package/dist/window/mouse.js +4 -2
  98. package/dist/window/video-mode.js +2 -1
  99. package/dist/window/window.js +19 -12
  100. package/native/addon.cc +25 -12
  101. package/native/audio-binding.cc +266 -126
  102. package/native/audio-codec-binding.cc +147 -77
  103. package/native/audio-device-binding.cc +76 -49
  104. package/native/audio-file-binding.cc +116 -67
  105. package/native/audio-recorder-binding.cc +147 -98
  106. package/native/audio-recorder.h +1 -1
  107. package/native/audio-state.h +53 -30
  108. package/native/audio-stream-binding.cc +148 -94
  109. package/native/audio-stream.h +5 -4
  110. package/native/audio-worker-binding.cc +163 -81
  111. package/native/audio-worker.h +35 -19
  112. package/native/batch-drawable.cc +29 -16
  113. package/native/batch-drawable.h +11 -8
  114. package/native/context-binding.cc +40 -27
  115. package/native/context-settings.h +15 -8
  116. package/native/deferred-delete.cc +9 -6
  117. package/native/deferred-delete.h +7 -8
  118. package/native/error-stream-binding.cc +42 -28
  119. package/native/font-binding.cc +89 -48
  120. package/native/graphics-binding.cc +122 -72
  121. package/native/graphics-state.h +50 -36
  122. package/native/image-binding.cc +38 -24
  123. package/native/image-state.h +26 -18
  124. package/native/input-binding.cc +42 -27
  125. package/native/render-window-binding.cc +38 -23
  126. package/native/shader-binding.cc +115 -50
  127. package/native/shape-binding.cc +94 -49
  128. package/native/shape-state.h +18 -9
  129. package/native/shaped-glyph-storage.h +9 -5
  130. package/native/stream-binding.cc +143 -117
  131. package/native/system-binding.cc +17 -12
  132. package/native/text-binding.cc +68 -35
  133. package/native/text-state.h +25 -18
  134. package/native/texture-binding.cc +42 -33
  135. package/native/texture-resource.h +20 -12
  136. package/native/time-value.h +3 -1
  137. package/native/transformable-binding.cc +12 -6
  138. package/native/transformable-state.h +6 -6
  139. package/native/value-binding.h +46 -28
  140. package/native/value-layout.h +10 -10
  141. package/native/values-binding.cc +29 -23
  142. package/native/vertex-binding.cc +18 -12
  143. package/native/vertex-buffer-binding.cc +38 -24
  144. package/native/vertex-storage.h +2 -2
  145. package/native/view-data.h +4 -3
  146. package/native/window-binding.cc +75 -45
  147. package/native/window-event.h +20 -11
  148. package/native/window-owner.h +15 -12
  149. package/package.json +40 -48
  150. package/src/audio/effect-processor.ts +9 -3
  151. package/src/audio/input-sound-file.ts +108 -36
  152. package/src/audio/listener.ts +39 -13
  153. package/src/audio/music.ts +112 -47
  154. package/src/audio/output-sound-file.ts +40 -11
  155. package/src/audio/playback-device.ts +23 -8
  156. package/src/audio/sound-buffer-recorder.ts +35 -13
  157. package/src/audio/sound-buffer.ts +166 -58
  158. package/src/audio/sound-file-factory.ts +127 -49
  159. package/src/audio/sound-file-reader.ts +49 -15
  160. package/src/audio/sound-recorder.ts +100 -34
  161. package/src/audio/sound-source.ts +142 -45
  162. package/src/audio/sound-stream.ts +15 -5
  163. package/src/audio/sound.ts +12 -4
  164. package/src/audio/value.ts +89 -26
  165. package/src/graphics/blend-mode.ts +3 -1
  166. package/src/graphics/boolean-vector.ts +56 -26
  167. package/src/graphics/color.ts +3 -1
  168. package/src/graphics/convex-shape.ts +10 -3
  169. package/src/graphics/font.ts +171 -50
  170. package/src/graphics/glsl-matrix.ts +9 -3
  171. package/src/graphics/glsl.ts +81 -35
  172. package/src/graphics/glyph.ts +67 -26
  173. package/src/graphics/image.ts +119 -45
  174. package/src/graphics/rect.ts +56 -24
  175. package/src/graphics/render-states.ts +31 -14
  176. package/src/graphics/render-target.ts +197 -81
  177. package/src/graphics/render-texture.ts +36 -12
  178. package/src/graphics/render-window.ts +9 -3
  179. package/src/graphics/shader.ts +186 -61
  180. package/src/graphics/shape.ts +93 -35
  181. package/src/graphics/sprite.ts +64 -25
  182. package/src/graphics/stencil-mode.ts +12 -6
  183. package/src/graphics/swap.ts +3 -2
  184. package/src/graphics/text.ts +229 -74
  185. package/src/graphics/texture.ts +180 -61
  186. package/src/graphics/transform.ts +132 -47
  187. package/src/graphics/transformable.ts +3 -1
  188. package/src/graphics/vertex-array.ts +87 -35
  189. package/src/graphics/vertex-buffer.ts +97 -33
  190. package/src/graphics/vertex.ts +9 -3
  191. package/src/graphics/view.ts +59 -21
  192. package/src/index.ts +101 -23
  193. package/src/internal/audio-codec-registry.ts +18 -6
  194. package/src/internal/audio-input-stream.ts +6 -2
  195. package/src/internal/audio-music-pump.ts +116 -41
  196. package/src/internal/audio-native.ts +249 -96
  197. package/src/internal/audio-recorder-session.ts +68 -24
  198. package/src/internal/audio-worker-session.ts +65 -21
  199. package/src/internal/audio-worker.ts +85 -41
  200. package/src/internal/glsl-value.ts +26 -11
  201. package/src/internal/graphics-state.ts +57 -20
  202. package/src/internal/input-stream.ts +23 -10
  203. package/src/internal/native.ts +252 -99
  204. package/src/internal/numeric-properties.ts +2 -1
  205. package/src/internal/render-states.ts +3 -1
  206. package/src/internal/scalar.ts +33 -14
  207. package/src/internal/shaped-glyph.ts +25 -12
  208. package/src/internal/struct-view.ts +40 -13
  209. package/src/internal/transformable.ts +3 -1
  210. package/src/network/common.ts +35 -11
  211. package/src/network/dns.ts +95 -38
  212. package/src/network/ftp.ts +129 -47
  213. package/src/network/http.ts +232 -77
  214. package/src/network/ip-address.ts +118 -48
  215. package/src/network/packet.ts +161 -54
  216. package/src/network/sftp.ts +498 -168
  217. package/src/network/socket-selector.ts +66 -26
  218. package/src/network/socket.ts +133 -46
  219. package/src/network/tcp-listener.ts +78 -29
  220. package/src/network/tcp-socket.ts +240 -95
  221. package/src/network/tls-material.ts +6 -2
  222. package/src/network/udp-socket.ts +147 -53
  223. package/src/system/angle.ts +3 -1
  224. package/src/system/clock.ts +12 -4
  225. package/src/system/err.ts +5 -2
  226. package/src/system/file-input-stream.ts +12 -4
  227. package/src/system/input-stream.ts +9 -3
  228. package/src/system/operators.ts +290 -115
  229. package/src/system/sleep.ts +6 -2
  230. package/src/system/time.ts +18 -6
  231. package/src/system/timeout-with-predicate.ts +19 -8
  232. package/src/system/vector2.ts +101 -49
  233. package/src/system/vector3.ts +85 -36
  234. package/src/window/clipboard.ts +3 -1
  235. package/src/window/context.ts +15 -5
  236. package/src/window/cursor.ts +3 -1
  237. package/src/window/event.ts +26 -12
  238. package/src/window/mouse.ts +6 -2
  239. package/src/window/video-mode.ts +3 -1
  240. package/src/window/window.ts +119 -37
  241. package/test/native/audio-probes.cc +74 -36
  242. package/test/native/deferred-delete-probes.cc +17 -11
  243. package/test/native/drawable-probes.cc +70 -36
  244. package/test/native/exception-probes.cc +14 -9
  245. package/test/native/image-probes.cc +20 -10
  246. package/test/native/matrix-probes.cc +8 -4
  247. package/test/native/network-oracle.cc +17 -11
  248. package/test/native/render-texture-probes.cc +33 -24
  249. package/test/native/shader-probes.cc +9 -9
  250. package/test/native/shape-probes.cc +37 -23
  251. package/test/native/sprite-probes.cc +41 -25
  252. package/test/native/system-probes.cc +58 -35
  253. package/test/native/text-probes.cc +77 -44
  254. package/test/native/texture-probes.cc +43 -26
  255. package/test/native/time-probes.cc +18 -12
  256. package/test/native/transform-probes.cc +15 -10
  257. package/test/native/transformable-probes.cc +23 -17
  258. package/test/native/value-oracle.h +9 -4
  259. package/test/native/value-probes.cc +31 -23
  260. package/test/native/vertex-array-probes.cc +22 -14
  261. package/test/native/vertex-buffer-probes.cc +28 -17
  262. package/test/native/view-probes.cc +29 -17
  263. package/test/native/window-probes.cc +66 -33
  264. package/tools/ensure-sfml.cjs +9 -0
  265. package/tools/generate-network-constants.cjs +11 -6
  266. package/tools/generate-window-constants.cjs +31 -12
  267. package/docs/README.ja.md +0 -30
  268. package/docs/README.ko.md +0 -30
  269. package/docs/README.md +0 -30
  270. package/docs/README.zh-CN.md +0 -30
  271. package/docs/api.ja.md +0 -84
  272. package/docs/api.ko.md +0 -84
  273. package/docs/api.md +0 -81
  274. package/docs/api.zh-CN.md +0 -81
  275. package/docs/audio.ja.md +0 -249
  276. package/docs/audio.ko.md +0 -251
  277. package/docs/audio.md +0 -252
  278. package/docs/audio.zh-CN.md +0 -252
  279. package/docs/concepts.ja.md +0 -130
  280. package/docs/concepts.ko.md +0 -130
  281. package/docs/concepts.md +0 -131
  282. package/docs/concepts.zh-CN.md +0 -131
  283. package/docs/development.ja.md +0 -144
  284. package/docs/development.ko.md +0 -144
  285. package/docs/development.md +0 -146
  286. package/docs/development.zh-CN.md +0 -146
  287. package/docs/getting-started.ja.md +0 -154
  288. package/docs/getting-started.ko.md +0 -154
  289. package/docs/getting-started.md +0 -156
  290. package/docs/getting-started.zh-CN.md +0 -156
  291. package/docs/graphics.ja.md +0 -256
  292. package/docs/graphics.ko.md +0 -254
  293. package/docs/graphics.md +0 -255
  294. package/docs/graphics.zh-CN.md +0 -257
  295. package/docs/network.ja.md +0 -214
  296. package/docs/network.ko.md +0 -216
  297. package/docs/network.md +0 -218
  298. package/docs/network.zh-CN.md +0 -218
  299. package/docs/system.ja.md +0 -169
  300. package/docs/system.ko.md +0 -171
  301. package/docs/system.md +0 -173
  302. package/docs/system.zh-CN.md +0 -173
  303. package/docs/window.ja.md +0 -138
  304. package/docs/window.ko.md +0 -140
  305. package/docs/window.md +0 -141
  306. package/docs/window.zh-CN.md +0 -141
  307. package/native/exception-boundary.h +0 -97
  308. package/native/numeric-fields.h +0 -96
  309. package/native/shared-handle.h +0 -107
  310. package/test/tsconfig.json +0 -8
  311. package/tools/configure-lsp.cjs +0 -23
  312. package/tools/lib_downloader.cjs +0 -92
  313. package/tools/lib_downloader_urls.cjs +0 -23
@@ -1,146 +0,0 @@
1
- # 开发指南
2
-
3
- [English](development.md) · **简体中文** · [日本語](development.ja.md) · [한국어](development.ko.md)
4
-
5
- > 本文面向修改源码、维护文档及运行仓库测试的贡献者。作为依赖使用时,从 [快速开始](getting-started.zh-CN.md) 阅读。
6
-
7
- [文档首页](README.zh-CN.md) · [API 导航](api.zh-CN.md) · [示例目录](../examples/README.zh-CN.md)
8
-
9
- <a id="get-the-source"></a>
10
-
11
- ## 获取源码
12
-
13
- 准备 Node.js、Python 与 C++20 工具链,平台安装命令见 [安装环境](getting-started.zh-CN.md#requirements),然后执行:
14
-
15
- ```sh
16
- git clone https://github.com/XadillaX/node-sfml.git
17
- cd node-sfml
18
- npm ci
19
- ```
20
-
21
- `install` 编译 Native 模块,`prepare` 生成 TypeScript 常量、JavaScript 与声明文件。构建钩子会先检查并下载 SFML 3.1.0。作为 npm 依赖安装时使用发布包中的 dist,只需在安装阶段编译 Native。
22
-
23
- ## 构建
24
-
25
- 以下命令均在仓库根目录执行:
26
-
27
- | 命令 | 用途 |
28
- | --- | --- |
29
- | `npm run build` | 编译 Native 与 TypeScript |
30
- | `npm run build:native` | 编译 Native 并更新 clangd 配置 |
31
- | `npm run build:ts` | 生成常量并编译 TypeScript |
32
- | `npm run build:docs` | 构建四语官网与生成的 API 参考 |
33
- | `npm run build:reference` | 单独生成 TypeDoc API 文档 |
34
- | `npm run docs:dev` | 启动官网开发预览 |
35
- | `npm run docs:preview` | 在本地预览官网生产构建 |
36
- | `npm run lint` | 检查源码、工具、测试和示例 |
37
- | `npm run test:types` | 验证 TypeScript 接口 |
38
- | `npm run test:runtime` | 串行运行运行时测试,需要先构建 |
39
- | `npm test` | 依次执行 lint、构建、类型检查和运行时测试 |
40
- | `npm pack --dry-run` | 检查 npm 包文件清单 |
41
-
42
- 只修改 TypeScript 时可执行 `npm run build:ts`;修改 Native 后执行 `npm run build`。运行时测试不会自动重建,运行前确保构建与源码一致。
43
-
44
- <a id="testing"></a>
45
-
46
- ## 测试与验证
47
-
48
- ```sh
49
- npm test
50
- ```
51
-
52
- `npm test` 执行 lint、Native 与 TypeScript 构建、类型检查和运行时测试。
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
- 生成文档不需要编译或加载 Native 模块;文档专用环境可先执行 `npm ci --ignore-scripts`。`npm run build:reference` 单独生成 TypeDoc 至 `build/docs/`,译文位于其中的 `zh/`、`ja/` 和 `ko/` 子目录。`npm --prefix site test` 验证注释本地化、链接转换与旧链接跳转,生产构建还会检查路由、锚点和资源。
86
-
87
- [Publish Docs 工作流](../.github/workflows/publish-docs.yml) 在 `main` 更新时运行,也支持手动触发。生成结果提交到 `gh-pages` 分支的 `docs/`,保留该分支根目录的文件,并沿用现有 `CNAME`(`sfml.js.org`)。生成内容没有变化时跳过提交。
88
-
89
- 旧 TypeDoc 类、接口等链接会跳转到对应的英文参考页面,并保留片段锚点。API 语言切换保留当前页面和成员锚点。
90
-
91
- JSDoc 先写英文正文,再依次写 `@zh`、`@ja` 和 `@ko` 译文。每组译文紧跟对应的正文或块标签;参数译文使用 `@zh 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.zh-CN.md)、[功能示例](../examples/features/README.zh-CN.md)、[官方示例](../examples/official/README.zh-CN.md) 和 [游戏与应用](../examples/projects/README.zh-CN.md)。命令和 [截图支持](../examples/features/README.zh-CN.md#screenshots) 随入口说明。构建后直接运行脚本,仅对支持的入口传入 `--frames`。
120
-
121
- ## 源码与生成文件
122
-
123
- | 目录 | 内容 |
124
- | --- | --- |
125
- | `src/` | TypeScript 实现 |
126
- | `native/` | C++ 绑定 |
127
- | `test/` | 运行时、类型和原生对照测试 |
128
- | `tools/` | 常量生成器、基准与测试工具 |
129
- | `docs/` | API 与开发文档 |
130
- | `site/` | 官网主题、多语言、搜索与构建脚本 |
131
-
132
- `build/`、`dist/`、`node_modules/` 和下载的 SFML 均为生成内容。窗口与网络常量由当前 SFML 头文件生成,不直接编辑 `src/*/gen/constants.ts`。
133
-
134
- Native 构建后自动生成 `build/compile_commands.json`,供 `.clangd` 使用。只更新语言服务配置时执行 `npm run configure:lsp`;编辑器仍显示旧诊断时,重启 clangd。
135
-
136
- ## 实现约定
137
-
138
- 值类型通过 TypedArray 计算与共享存储,Native 资源及其视图负责内存保活。图形资源在所属线程销毁;绘制记录必须保持快照语义,不能因后续属性修改改变已录制结果。
139
-
140
- 相关入口包括 `src/internal/lazy-value.ts`、`src/internal/graphics-state.ts`、`native/shared-handle.h`、`native/deferred-delete.h`、`native/batch-drawable.h`。添加公开字段和方法时补充说明功能、参数及上游对应关系的 JSDoc。
141
-
142
- 下载器、安装钩子和平台构建相互关联,修改时需要验证对应平台。下载地址及架构映射在 `tools/lib_downloader_urls.cjs`,缓存位于 `third_party/sfml/`。
143
-
144
- ## 提交变更
145
-
146
- PR 说明具体行为、相关验证及未验证的平台路径。Native 变更运行受影响的原生对照测试;纯文档变更检查链接、代码示例与 TypeDoc 构建。性能数字应附机器、Node.js/SFML 版本、场景和测量方法。
@@ -1,154 +0,0 @@
1
- # クイックスタート
2
-
3
- [English](getting-started.md) / [简体中文](getting-started.zh-CN.md) / **日本語** / [한국어](getting-started.ko.md)
4
-
5
- > 目標は、sfml.js をインストールし、閉じるイベントに応答できるネイティブウィンドウを動かすことです。このガイドでは現在の SFML 3.1.0 API を使います。
6
-
7
- [ドキュメントトップ](README.ja.md) · [基本概念](concepts.ja.md) · [サンプル](../examples/README.ja.md)
8
-
9
- <a id="requirements"></a>
10
- ## 必要な環境
11
-
12
- sfml.js は Node.js のネイティブ拡張です。インストール時に現在のプラットフォーム向けの SFML 動的ライブラリをダウンロードし、ローカルでバインディングをコンパイルします。Python と C++20 ツールチェーンが必要です。
13
-
14
- パッケージが宣言する Node.js の対応範囲は `^18.19.0 || >=20.5.0` で、現在の CI 設定は Node.js 20 と 22 を使っています。初めて環境を構築する場合は Node.js 22 を利用できます。
15
-
16
- ### macOS
17
-
18
- macOS 13+ の x64、arm64 をダウンロード対象としてサポートしています。Xcode Command Line Tools をインストールし、Python が利用できることを確認します。
19
-
20
- ```sh
21
- xcode-select --install
22
- python3 --version
23
- ```
24
-
25
- ダウンロードする SFML のアーキテクチャは Node.js のアーキテクチャで決まります。`node -p process.arch` で確認できます。
26
-
27
- ### Linux
28
-
29
- 現在、自動ダウンロードに対応しているのは x64 です。Ubuntu/Debian では、リポジトリの CI と同じ依存パッケージをインストールできます。
30
-
31
- ```sh
32
- sudo apt-get update
33
- sudo apt-get install -y \
34
- build-essential python3 \
35
- libgl1-mesa-dev libx11-dev libxrandr-dev libxcursor-dev libxi-dev \
36
- libudev-dev libfreetype-dev libflac-dev libvorbis-dev \
37
- libopenal-dev libmbedtls-dev
38
- ```
39
-
40
- ディスプレイのない CI では `xvfb` と `xauth` も必要です。実行方法は[開発ガイド](development.ja.md#testing)を参照してください。他のディストリビューションでは対応する開発用パッケージを使います。
41
-
42
- ### Windows
43
-
44
- Python と Visual Studio 2022 Build Tools をインストールし、「C++ によるデスクトップ開発」と Windows SDK を選択します。現在のダウンロード対象は x64、ia32 です。ビルドツールチェーンのアーキテクチャは Node.js と一致させてください。
45
-
46
- ## パッケージのインストール
47
-
48
- アプリケーションのディレクトリで実行します。
49
-
50
- ```sh
51
- npm install sfml.js
52
- ```
53
-
54
- TypeScript の型宣言はパッケージに含まれています。npm は既定で `latest` タグをインストールします。次のコマンドでインストール済みのバージョンと公開タグを確認できます。
55
-
56
- ```sh
57
- npm ls sfml.js
58
- npm view sfml.js dist-tags
59
- ```
60
-
61
- 現在のリポジトリを直接試す場合は、[開発ガイド](development.ja.md#get-the-source)に従って `npm ci` を実行してから、リポジトリのサンプルを動かしてください。
62
-
63
- インストールされたファイルは依存パッケージ内の `third_party/sfml/` に、ネイティブモジュールは `build/Release/sfml.node` に保存されます。ダウンロードには SFML の GitHub Release へのアクセスが必要です。バージョンとアーキテクチャが一致する場合はキャッシュを再利用します。
64
-
65
- `SFML_DOWNLOAD_MIRROR` でダウンロード用プロキシの接頭辞を指定できます。最終的な URL は `<接頭辞>/<完全な GitHub URL>` になります。使用するプロキシはこの形式に対応している必要があります。設定については[ダウンロード URL の実装](../tools/lib_downloader_urls.cjs)を参照してください。
66
-
67
- ## 最初のウィンドウを開く
68
-
69
- `hello.cjs` を作成します。
70
-
71
- ```javascript
72
- const sf = require('sfml.js');
73
-
74
- const window = new sf.RenderWindow(
75
- new sf.VideoMode(new sf.Vector2u(800, 600)),
76
- 'Hello, sfml.js',
77
- );
78
- const circle = new sf.CircleShape({ radius: 80 });
79
- circle.setPosition(new sf.Vector2f(320, 220));
80
- circle.setFillColor(new sf.Color(76, 190, 110));
81
- window.setFramerateLimit(60);
82
-
83
- function frame() {
84
- window.handleEvents({
85
- Closed: () => window.close(),
86
- KeyPressed: event => {
87
- if (event.code === sf.Keyboard.Key.Escape) window.close();
88
- },
89
- });
90
- if (!window.isOpen()) return;
91
-
92
- window.clear(new sf.Color(24, 28, 32));
93
- window.draw(circle);
94
- window.display();
95
- setImmediate(frame);
96
- }
97
-
98
- frame();
99
- ```
100
-
101
- `node hello.cjs` を実行すると、ウィンドウに緑色の円が表示されます。Esc キーまたは閉じるボタンで終了します。
102
-
103
- 各フレームでは、最初にイベントを処理し、続いてシーンの更新、画面のクリア、描画、表示を行います。`setImmediate(frame)` は次のイベントループで描画を再開し、ファイル、ネットワーク、Worker のメッセージ処理に実行機会を与えます。`display()` は同期インターフェースで、フレームレート制限や垂直同期によって待機する場合があります。対応する `displayAsync()` メソッドはありません。
104
-
105
- ## TypeScript の使用
106
-
107
- 公開型はパッケージのエントリーポイントからインポートします。
108
-
109
- ```typescript
110
- import { RenderWindow, Vector2u } from 'sfml.js';
111
-
112
- const window = new RenderWindow(new Vector2u(800, 600), 'TypeScript');
113
- window.close();
114
- ```
115
-
116
- マイクロ秒単位の時間と一部のネットワーク整数には `bigint` を使うため、アプリケーションの TypeScript の `target` は `ES2020` 以上にしてください。CommonJS アプリケーションでは `require('sfml.js')` を使い、型パッケージを別途インストールする必要はありません。
117
-
118
- ## 画像の読み込み
119
-
120
- まずリソースを作成し、読み込みの成功を待ってから、それを使うオブジェクトを作成します。
121
-
122
- ```javascript
123
- const sf = require('sfml.js');
124
-
125
- async function loadSprite(filename) {
126
- const texture = new sf.Texture();
127
- if (!await texture.loadFromFile(filename)) {
128
- throw new Error(`Cannot load texture: ${filename}`);
129
- }
130
- return new sf.Sprite(texture);
131
- }
132
- ```
133
-
134
- 返された Sprite をウィンドウの `draw()` に渡します。相対ファイルパスは呼び出し時の作業ディレクトリを基準に解決されます。
135
-
136
- 通常、ファイルが存在しない場合やデコードに失敗した場合は `false` を返します。型エラー、範囲エラー、実行時の異常は例外または Promise の reject で通知されます。例外だけを捕捉して、読み込みの戻り値を無視しないでください。
137
-
138
- ## よくある問題
139
-
140
- | 症状 | 確認事項 |
141
- | --- | --- |
142
- | `sfml.node` が見つからない | インストールスクリプトが無効になっていないか確認。ツールチェーンを確認してから、アプリケーション内で `npm rebuild sfml.js` を実行 |
143
- | `Unsupported SFML platform` | 対応する OS と `process.arch` を確認。現在 Linux arm64 用の自動ダウンロードパッケージはない |
144
- | ウィンドウや OpenGL コンテキストを作成できない | グラフィカルセッションと OpenGL ドライバーの有無を確認。Linux CI では Xvfb を使用 |
145
- | ウィンドウが応答しない、非同期タスクが完了しない | フレームループが `setImmediate` などでイベントループに制御を返しているか確認 |
146
- | `await load...()` が例外を投げないのに何も表示されない | 真偽値の戻り値、ファイルパス、Sprite の位置、テクスチャ矩形を確認 |
147
- | 中国語のテキストが表示されない | 対象の文字を収録したフォントを `Font.openFromFile()` で読み込む |
148
-
149
- 次は[基本概念](concepts.ja.md)を読むか、[完全なサンプル](../examples/README.ja.md)を実行してください。
150
-
151
- <a id="sfml-cpp-reference"></a>
152
- ## SFML C++ リファレンス
153
-
154
- [SFML 3.1.0 公式リファレンス](https://www.sfml-dev.org/documentation/3.1.0/)のサンプルは、上流の概念を理解するために利用できます。ただし、C++ のファイル読み込みコンストラクターやブロッキングするループを、そのまま JavaScript にコピーすることはできません。リソースの非同期読み込みと Node.js のイベントループについては、このガイドの方法に従ってください。
@@ -1,154 +0,0 @@
1
- # 빠른 시작
2
-
3
- [English](getting-started.md) / [简体中文](getting-started.zh-CN.md) / [日本語](getting-started.ja.md) / **한국어**
4
-
5
- > 목표: sfml.js를 설치하고 닫기 이벤트에 응답하는 네이티브 창을 실행합니다. 이 문서는 현재의 SFML 3.1.0 API를 사용합니다.
6
-
7
- [문서 홈](README.ko.md) · [핵심 개념](concepts.ko.md) · [예제](../examples/README.ko.md)
8
-
9
- <a id="requirements"></a>
10
- ## 설치 환경
11
-
12
- sfml.js는 Node.js 네이티브 확장입니다. 설치 과정에서 현재 플랫폼용 SFML 동적 라이브러리를 다운로드하고 로컬에서 바인딩을 컴파일하므로 Python과 C++20 도구 체인이 필요합니다.
13
-
14
- 패키지에 선언된 Node.js 지원 범위는 `^18.19.0 || >=20.5.0`이며, 현재 CI 구성은 Node.js 20과 22를 사용합니다. 처음 설정할 때는 Node.js 22를 사용할 수 있습니다.
15
-
16
- ### macOS
17
-
18
- macOS 13+의 x64, arm64 다운로드 대상을 지원합니다. Xcode Command Line Tools를 설치하고 Python을 사용할 수 있는지 확인하세요.
19
-
20
- ```sh
21
- xcode-select --install
22
- python3 --version
23
- ```
24
-
25
- Node.js 아키텍처에 따라 다운로드할 SFML 아키텍처가 결정됩니다. `node -p process.arch`로 확인할 수 있습니다.
26
-
27
- ### Linux
28
-
29
- 현재 자동 다운로드는 x64를 지원합니다. Ubuntu/Debian에서는 저장소 CI와 동일하게 의존성을 설치할 수 있습니다.
30
-
31
- ```sh
32
- sudo apt-get update
33
- sudo apt-get install -y \
34
- build-essential python3 \
35
- libgl1-mesa-dev libx11-dev libxrandr-dev libxcursor-dev libxi-dev \
36
- libudev-dev libfreetype-dev libflac-dev libvorbis-dev \
37
- libopenal-dev libmbedtls-dev
38
- ```
39
-
40
- 디스플레이가 없는 CI에는 `xvfb`와 `xauth`도 필요합니다. 실행 방법은 [개발 가이드](development.ko.md#testing)를 참고하세요. 다른 배포판에서는 이에 해당하는 개발 패키지를 사용합니다.
41
-
42
- ### Windows
43
-
44
- Python과 Visual Studio 2022 Build Tools를 설치하고, 'C++를 사용한 데스크톱 개발'과 Windows SDK를 선택하세요. 현재 다운로드 대상은 x64, ia32이며, 컴파일 도구 체인은 Node.js 아키텍처와 일치해야 합니다.
45
-
46
- ## 패키지 설치
47
-
48
- 애플리케이션 디렉터리에서 실행하세요.
49
-
50
- ```sh
51
- npm install sfml.js
52
- ```
53
-
54
- TypeScript 타입 선언은 패키지에 포함되어 있습니다. npm은 기본적으로 `latest` 태그를 설치합니다. 다음 명령으로 설치된 버전과 배포 태그를 확인할 수 있습니다.
55
-
56
- ```sh
57
- npm ls sfml.js
58
- npm view sfml.js dist-tags
59
- ```
60
-
61
- 현재 저장소를 직접 사용해 보려면 [개발 가이드](development.ko.md#get-the-source)에 따라 `npm ci`를 실행한 뒤 저장소 예제를 실행하세요.
62
-
63
- 설치 파일은 의존성 패키지의 `third_party/sfml/`에, 네이티브 모듈은 `build/Release/sfml.node`에 저장됩니다. 다운로드 시 SFML의 GitHub Release에 접근할 수 있어야 하며, 버전과 아키텍처가 일치하면 캐시를 재사용합니다.
64
-
65
- `SFML_DOWNLOAD_MIRROR`로 다운로드 프록시 접두사를 지정할 수 있습니다. 최종 URL은 `<접두사>/<전체 GitHub URL>` 형식이므로, 사용하는 프록시는 이 형식을 지원해야 합니다. 설정은 [다운로드 URL 구현](../tools/lib_downloader_urls.cjs)을 참고하세요.
66
-
67
- ## 첫 번째 창 열기
68
-
69
- `hello.cjs`를 만드세요.
70
-
71
- ```javascript
72
- const sf = require('sfml.js');
73
-
74
- const window = new sf.RenderWindow(
75
- new sf.VideoMode(new sf.Vector2u(800, 600)),
76
- 'Hello, sfml.js',
77
- );
78
- const circle = new sf.CircleShape({ radius: 80 });
79
- circle.setPosition(new sf.Vector2f(320, 220));
80
- circle.setFillColor(new sf.Color(76, 190, 110));
81
- window.setFramerateLimit(60);
82
-
83
- function frame() {
84
- window.handleEvents({
85
- Closed: () => window.close(),
86
- KeyPressed: event => {
87
- if (event.code === sf.Keyboard.Key.Escape) window.close();
88
- },
89
- });
90
- if (!window.isOpen()) return;
91
-
92
- window.clear(new sf.Color(24, 28, 32));
93
- window.draw(circle);
94
- window.display();
95
- setImmediate(frame);
96
- }
97
-
98
- frame();
99
- ```
100
-
101
- `node hello.cjs`를 실행하면 창에 초록색 원이 표시됩니다. Esc 키를 누르거나 닫기 버튼을 클릭하면 종료됩니다.
102
-
103
- 매 프레임마다 이벤트를 먼저 처리한 뒤 장면 업데이트, 화면 지우기, 그리기, 표시를 수행합니다. `setImmediate(frame)`은 다음 이벤트 루프에서 그리기를 이어 가며, 파일, 네트워크, Worker 메시지가 처리될 기회를 줍니다. `display()`는 동기식 인터페이스로, 프레임 제한이나 수직 동기화 때문에 대기할 수 있습니다. 이에 대응하는 `displayAsync()` 메서드는 없습니다.
104
-
105
- ## TypeScript 사용
106
-
107
- 패키지 진입점에서 공개 타입을 가져옵니다.
108
-
109
- ```typescript
110
- import { RenderWindow, Vector2u } from 'sfml.js';
111
-
112
- const window = new RenderWindow(new Vector2u(800, 600), 'TypeScript');
113
- window.close();
114
- ```
115
-
116
- 마이크로초 단위 시간과 일부 네트워크 정수는 `bigint`를 사용하므로, 애플리케이션의 TypeScript `target`은 최소 `ES2020`이어야 합니다. CommonJS 애플리케이션에서는 `require('sfml.js')`를 사용하며, 타입 패키지를 별도로 설치할 필요가 없습니다.
117
-
118
- ## 이미지 로딩
119
-
120
- 먼저 리소스를 생성하고 로딩이 성공할 때까지 기다린 다음, 이를 사용하는 객체를 생성합니다.
121
-
122
- ```javascript
123
- const sf = require('sfml.js');
124
-
125
- async function loadSprite(filename) {
126
- const texture = new sf.Texture();
127
- if (!await texture.loadFromFile(filename)) {
128
- throw new Error(`Cannot load texture: ${filename}`);
129
- }
130
- return new sf.Sprite(texture);
131
- }
132
- ```
133
-
134
- 반환된 Sprite를 창의 `draw()` 호출에 전달하세요. 상대 파일 경로는 호출 시점의 작업 디렉터리를 기준으로 해석됩니다.
135
-
136
- 일반적인 파일 부재나 디코딩 실패는 보통 `false`를 반환합니다. 타입 오류, 범위 오류, 실행 중 예외는 예외 발생이나 Promise 거부로 보고됩니다. 예외만 잡고 로딩 반환값을 무시해서는 안 됩니다.
137
-
138
- ## 자주 발생하는 문제
139
-
140
- | 증상 | 확인할 사항 |
141
- | --- | --- |
142
- | `sfml.node`를 찾을 수 없음 | 설치 스크립트가 비활성화되었는지 확인하고, 도구 체인을 준비한 뒤 애플리케이션에서 `npm rebuild sfml.js` 실행 |
143
- | `Unsupported SFML platform` | 지원되는 운영체제와 `process.arch` 확인. 현재 Linux arm64 자동 다운로드 패키지는 없음 |
144
- | 창이나 OpenGL 컨텍스트를 생성할 수 없음 | 그래픽 세션과 OpenGL 드라이버 확인. Linux CI에서는 Xvfb 사용 |
145
- | 창이 응답하지 않고 비동기 작업이 완료되지 않음 | 프레임 루프가 `setImmediate` 등의 방식으로 이벤트 루프에 제어권을 넘기는지 확인 |
146
- | `await load...()`에서 예외가 없었지만 화면이 나오지 않음 | 불리언 반환값, 파일 경로, Sprite 위치, 텍스처 사각형 확인 |
147
- | 텍스트에 중국어가 표시되지 않음 | 해당 문자를 지원하는 폰트를 사용하고 `Font.openFromFile()`로 로드 |
148
-
149
- 다음으로 [핵심 개념](concepts.ko.md)을 읽거나 [전체 예제](../examples/README.ko.md)를 바로 실행해 보세요.
150
-
151
- <a id="sfml-cpp-reference"></a>
152
- ## SFML C++ 레퍼런스
153
-
154
- [SFML 3.1.0 공식 문서](https://www.sfml-dev.org/documentation/3.1.0/)의 원본 예제에서 창과 렌더링의 기본 개념을 확인할 수 있습니다. C++의 파일 생성자나 블로킹 루프를 JavaScript에 그대로 옮겨서는 안 됩니다. 이 가이드처럼 리소스 로딩을 기다리고 이벤트 루프에 제어권을 넘겨야 합니다.
@@ -1,156 +0,0 @@
1
- # Quick Start
2
-
3
- **English** · [简体中文](getting-started.zh-CN.md) · [日本語](getting-started.ja.md) · [한국어](getting-started.ko.md)
4
-
5
- > Goal: install sfml.js and run a native window that responds to close events. This guide uses the current SFML 3.1.0 API.
6
-
7
- [Documentation](README.md) · [Core concepts](concepts.md) · [Examples](../examples/README.md)
8
-
9
- <a id="requirements"></a>
10
-
11
- ## Requirements
12
-
13
- sfml.js is a native Node.js addon. Installation downloads SFML shared libraries for the current platform and compiles the binding locally; Python and a C++20 toolchain are required.
14
-
15
- The package declares Node.js `^18.19.0 || >=20.5.0`; the existing CI configuration uses Node.js 20 and 22. Node.js 22 is a suitable choice for a new setup.
16
-
17
- ### macOS
18
-
19
- Download targets support x64 and arm64 on macOS 13+. Install Xcode Command Line Tools and confirm Python is available:
20
-
21
- ```sh
22
- xcode-select --install
23
- python3 --version
24
- ```
25
-
26
- The Node.js architecture determines which SFML architecture is downloaded; check it with `node -p process.arch`.
27
-
28
- ### Linux
29
-
30
- Automatic downloads currently support x64. On Ubuntu/Debian, install dependencies as configured in the repository CI:
31
-
32
- ```sh
33
- sudo apt-get update
34
- sudo apt-get install -y \
35
- build-essential python3 \
36
- libgl1-mesa-dev libx11-dev libxrandr-dev libxcursor-dev libxi-dev \
37
- libudev-dev libfreetype-dev libflac-dev libvorbis-dev \
38
- libopenal-dev libmbedtls-dev
39
- ```
40
-
41
- Headless CI also requires `xvfb` and `xauth`; see the [development guide](development.md#testing) for execution instructions. Use the equivalent development packages on other distributions.
42
-
43
- ### Windows
44
-
45
- Install Python and Visual Studio 2022 Build Tools, selecting "Desktop development with C++" and the Windows SDK. Current download targets are x64 and ia32; the compiler toolchain must match the Node.js architecture.
46
-
47
- ## Install the package
48
-
49
- Run from your application directory:
50
-
51
- ```sh
52
- npm install sfml.js
53
- ```
54
-
55
- TypeScript declarations are included in the package. npm installs the `latest` tag by default; inspect the installed version and distribution tags with:
56
-
57
- ```sh
58
- npm ls sfml.js
59
- npm view sfml.js dist-tags
60
- ```
61
-
62
- To try the current repository directly, follow the [development guide](development.md#get-the-source), run `npm ci`, then run the repository examples.
63
-
64
- Installed SFML files are stored in the dependency package's `third_party/sfml/`; the native module is at `build/Release/sfml.node`. Downloads require access to SFML's GitHub Release; the cache is reused when the version and architecture match.
65
-
66
- `SFML_DOWNLOAD_MIRROR` specifies a download proxy prefix. The final URL is `<prefix>/<full GitHub URL>`; the proxy must support this format. See the [download URL implementation](../tools/lib_downloader_urls.cjs) for configuration.
67
-
68
- ## Open your first window
69
-
70
- Create `hello.cjs`:
71
-
72
- ```javascript
73
- const sf = require('sfml.js');
74
-
75
- const window = new sf.RenderWindow(
76
- new sf.VideoMode(new sf.Vector2u(800, 600)),
77
- 'Hello, sfml.js',
78
- );
79
- const circle = new sf.CircleShape({ radius: 80 });
80
- circle.setPosition(new sf.Vector2f(320, 220));
81
- circle.setFillColor(new sf.Color(76, 190, 110));
82
- window.setFramerateLimit(60);
83
-
84
- function frame() {
85
- window.handleEvents({
86
- Closed: () => window.close(),
87
- KeyPressed: event => {
88
- if (event.code === sf.Keyboard.Key.Escape) window.close();
89
- },
90
- });
91
- if (!window.isOpen()) return;
92
-
93
- window.clear(new sf.Color(24, 28, 32));
94
- window.draw(circle);
95
- window.display();
96
- setImmediate(frame);
97
- }
98
-
99
- frame();
100
- ```
101
-
102
- Run `node hello.cjs` to display a green circle in a window. Press Esc or click the close button to exit.
103
-
104
- Each frame handles events first, then updates the scene, clears, draws and presents. `setImmediate(frame)` continues drawing on the next event-loop iteration, allowing file I/O, networking and Worker messages to run. `display()` is synchronous and may wait for a frame limit or vertical sync; there is no corresponding `displayAsync()` method.
105
-
106
- ## Use TypeScript
107
-
108
- Import public types from the package entry point:
109
-
110
- ```typescript
111
- import { RenderWindow, Vector2u } from 'sfml.js';
112
-
113
- const window = new RenderWindow(new Vector2u(800, 600), 'TypeScript');
114
- window.close();
115
- ```
116
-
117
- Microsecond time values and some network integers use `bigint`, so your application's TypeScript `target` must be at least `ES2020`. Use `require('sfml.js')` in CommonJS applications; no separate type package is needed.
118
-
119
- ## Load an image
120
-
121
- Create the resource, wait for successful loading, then create the object that uses it:
122
-
123
- ```javascript
124
- const sf = require('sfml.js');
125
-
126
- async function loadSprite(filename) {
127
- const texture = new sf.Texture();
128
- if (!await texture.loadFromFile(filename)) {
129
- throw new Error(`Cannot load texture: ${filename}`);
130
- }
131
- return new sf.Sprite(texture);
132
- }
133
- ```
134
-
135
- Pass the returned Sprite to the window's `draw()` call. Relative file paths are resolved against the working directory at call time.
136
-
137
- Ordinary missing-file or decoding failures usually return `false`; type errors, range errors and runtime failures are reported by throwing or rejecting a promise. Do not catch exceptions while ignoring the loading return value.
138
-
139
- ## Troubleshooting
140
-
141
- | Symptom | What to check |
142
- | --- | --- |
143
- | `sfml.node` cannot be found | Check whether installation scripts were disabled; after confirming the toolchain, run `npm rebuild sfml.js` in the application |
144
- | `Unsupported SFML platform` | Compare the supported systems with `process.arch`; there is currently no automatic Linux arm64 download |
145
- | Cannot create a window or OpenGL context | Check for a graphical session and OpenGL driver; use Xvfb in Linux CI |
146
- | Window is unresponsive or asynchronous tasks never finish | Check whether the frame loop yields to the event loop through `setImmediate` or an equivalent |
147
- | `await load...()` did not throw, but nothing appears | Check the boolean return value, file path, Sprite position and texture rectangle |
148
- | Text does not display Chinese characters | Use a font covering the required characters and load it with `Font.openFromFile()` |
149
-
150
- Continue with [core concepts](concepts.md), or run the [complete examples](../examples/README.md).
151
-
152
- <a id="sfml-cpp-reference"></a>
153
-
154
- ## SFML C++ reference
155
-
156
- The [original SFML 3.1.0 C++ reference](https://www.sfml-dev.org/documentation/3.1.0/) provides upstream concepts and examples. C++ file-loading constructors and blocking window loops cannot be copied verbatim into JavaScript: use the asynchronous resource methods and event-loop yielding shown here.