@jsprismarine/script-host 0.0.0 → 0.23.0-unstable-20261120210452

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 (440) hide show
  1. package/CHANGELOG.md +99 -0
  2. package/LICENSE +21 -0
  3. package/README.md +667 -28
  4. package/dist/ScriptEngine.d.ts +250 -0
  5. package/dist/ScriptEngine.d.ts.map +1 -0
  6. package/dist/ScriptEngine.js +427 -0
  7. package/dist/ScriptEngine.js.map +1 -0
  8. package/dist/absentGlobals.d.ts +29 -0
  9. package/dist/absentGlobals.d.ts.map +1 -0
  10. package/dist/absentGlobals.js +94 -0
  11. package/dist/absentGlobals.js.map +1 -0
  12. package/dist/debugger/DebugSession.d.ts +189 -0
  13. package/dist/debugger/DebugSession.d.ts.map +1 -0
  14. package/dist/debugger/DebugSession.js +588 -0
  15. package/dist/debugger/DebugSession.js.map +1 -0
  16. package/dist/debugger/EngineDebugger.d.ts +158 -0
  17. package/dist/debugger/EngineDebugger.d.ts.map +1 -0
  18. package/dist/debugger/EngineDebugger.js +174 -0
  19. package/dist/debugger/EngineDebugger.js.map +1 -0
  20. package/dist/debugger/channel.d.ts +67 -0
  21. package/dist/debugger/channel.d.ts.map +1 -0
  22. package/dist/debugger/channel.js +120 -0
  23. package/dist/debugger/channel.js.map +1 -0
  24. package/dist/debugger/connectionWorker.d.ts +2 -0
  25. package/dist/debugger/connectionWorker.d.ts.map +1 -0
  26. package/dist/debugger/connectionWorker.js +98 -0
  27. package/dist/debugger/connectionWorker.js.map +1 -0
  28. package/dist/debugger/framing.d.ts +46 -0
  29. package/dist/debugger/framing.d.ts.map +1 -0
  30. package/dist/debugger/framing.js +106 -0
  31. package/dist/debugger/framing.js.map +1 -0
  32. package/dist/debugger/profiler.d.ts +72 -0
  33. package/dist/debugger/profiler.d.ts.map +1 -0
  34. package/dist/debugger/profiler.js +92 -0
  35. package/dist/debugger/profiler.js.map +1 -0
  36. package/dist/debugger/protocol.d.ts +170 -0
  37. package/dist/debugger/protocol.d.ts.map +1 -0
  38. package/dist/debugger/protocol.js +141 -0
  39. package/dist/debugger/protocol.js.map +1 -0
  40. package/dist/debugger/thread.d.ts +85 -0
  41. package/dist/debugger/thread.d.ts.map +1 -0
  42. package/dist/debugger/thread.js +134 -0
  43. package/dist/debugger/thread.js.map +1 -0
  44. package/dist/debugger/transport.d.ts +80 -0
  45. package/dist/debugger/transport.d.ts.map +1 -0
  46. package/dist/debugger/transport.js +150 -0
  47. package/dist/debugger/transport.js.map +1 -0
  48. package/dist/engineSource.d.ts +14 -0
  49. package/dist/engineSource.d.ts.map +1 -0
  50. package/dist/engineSource.js +17 -0
  51. package/dist/engineSource.js.map +1 -0
  52. package/dist/errors.d.ts +62 -0
  53. package/dist/errors.d.ts.map +1 -0
  54. package/dist/errors.js +62 -0
  55. package/dist/errors.js.map +1 -0
  56. package/dist/ffi.d.ts +63 -0
  57. package/dist/ffi.d.ts.map +1 -0
  58. package/dist/ffi.js +156 -0
  59. package/dist/ffi.js.map +1 -0
  60. package/dist/generated/script-modules/common.d.ts +2 -0
  61. package/dist/generated/script-modules/common.js +262 -0
  62. package/dist/generated/script-modules/common.js.map +1 -0
  63. package/dist/generated/script-modules/common.json.d.ts +2 -0
  64. package/dist/generated/script-modules/debug-utilities.d.ts +2 -0
  65. package/dist/generated/script-modules/debug-utilities.js +23 -0
  66. package/dist/generated/script-modules/debug-utilities.js.map +1 -0
  67. package/dist/generated/script-modules/debug-utilities.json.d.ts +2 -0
  68. package/dist/generated/script-modules/diagnostics.d.ts +2 -0
  69. package/dist/generated/script-modules/diagnostics.js +281 -0
  70. package/dist/generated/script-modules/diagnostics.js.map +1 -0
  71. package/dist/generated/script-modules/diagnostics.json.d.ts +2 -0
  72. package/dist/generated/script-modules/server-admin.d.ts +2 -0
  73. package/dist/generated/script-modules/server-admin.js +23 -0
  74. package/dist/generated/script-modules/server-admin.js.map +1 -0
  75. package/dist/generated/script-modules/server-admin.json.d.ts +2 -0
  76. package/dist/generated/script-modules/server-gametest.d.ts +2 -0
  77. package/dist/generated/script-modules/server-gametest.js +23 -0
  78. package/dist/generated/script-modules/server-gametest.js.map +1 -0
  79. package/dist/generated/script-modules/server-gametest.json.d.ts +2 -0
  80. package/dist/generated/script-modules/server-graphics.d.ts +2 -0
  81. package/dist/generated/script-modules/server-graphics.js +30 -0
  82. package/dist/generated/script-modules/server-graphics.js.map +1 -0
  83. package/dist/generated/script-modules/server-graphics.json.d.ts +2 -0
  84. package/dist/generated/script-modules/server-net.d.ts +2 -0
  85. package/dist/generated/script-modules/server-net.js +24 -0
  86. package/dist/generated/script-modules/server-net.js.map +1 -0
  87. package/dist/generated/script-modules/server-net.json.d.ts +2 -0
  88. package/dist/generated/script-modules/server-ui.d.ts +2 -0
  89. package/dist/generated/script-modules/server-ui.js +110 -0
  90. package/dist/generated/script-modules/server-ui.js.map +1 -0
  91. package/dist/generated/script-modules/server-ui.json.d.ts +2 -0
  92. package/dist/generated/script-modules/server.d.ts +2 -0
  93. package/dist/generated/script-modules/server.js +251 -0
  94. package/dist/generated/script-modules/server.js.map +1 -0
  95. package/dist/generated/script-modules/server.json.d.ts +2 -0
  96. package/dist/generated/scriptApi.d.ts +3233 -0
  97. package/dist/generated/scriptApi.d.ts.map +1 -0
  98. package/dist/generated/scriptApi.js +0 -0
  99. package/dist/generated/scriptModules.d.ts +13 -0
  100. package/dist/generated/scriptModules.d.ts.map +1 -0
  101. package/dist/generated/scriptModules.js +34 -0
  102. package/dist/generated/scriptModules.js.map +1 -0
  103. package/dist/host/PackForms.d.ts +71 -0
  104. package/dist/host/PackForms.d.ts.map +1 -0
  105. package/dist/host/PackForms.js +164 -0
  106. package/dist/host/PackForms.js.map +1 -0
  107. package/dist/host/ScriptForms.d.ts +51 -0
  108. package/dist/host/ScriptForms.d.ts.map +1 -0
  109. package/dist/host/ScriptForms.js +103 -0
  110. package/dist/host/ScriptForms.js.map +1 -0
  111. package/dist/host/ScriptHttp.d.ts +54 -0
  112. package/dist/host/ScriptHttp.d.ts.map +1 -0
  113. package/dist/host/ScriptHttp.js +82 -0
  114. package/dist/host/ScriptHttp.js.map +1 -0
  115. package/dist/host/WorldScripts.d.ts +350 -0
  116. package/dist/host/WorldScripts.d.ts.map +1 -0
  117. package/dist/host/WorldScripts.js +1421 -0
  118. package/dist/host/WorldScripts.js.map +1 -0
  119. package/dist/host/blocksItems/blockComponents.d.ts +27 -0
  120. package/dist/host/blocksItems/blockComponents.d.ts.map +1 -0
  121. package/dist/host/blocksItems/blockComponents.js +73 -0
  122. package/dist/host/blocksItems/blockComponents.js.map +1 -0
  123. package/dist/host/blocksItems/blocks.d.ts +12 -0
  124. package/dist/host/blocksItems/blocks.d.ts.map +1 -0
  125. package/dist/host/blocksItems/blocks.js +247 -0
  126. package/dist/host/blocksItems/blocks.js.map +1 -0
  127. package/dist/host/blocksItems/componentFacts.d.ts +14 -0
  128. package/dist/host/blocksItems/componentFacts.d.ts.map +1 -0
  129. package/dist/host/blocksItems/componentFacts.js +34 -0
  130. package/dist/host/blocksItems/componentFacts.js.map +1 -0
  131. package/dist/host/blocksItems/containers.d.ts +18 -0
  132. package/dist/host/blocksItems/containers.d.ts.map +1 -0
  133. package/dist/host/blocksItems/containers.js +128 -0
  134. package/dist/host/blocksItems/containers.js.map +1 -0
  135. package/dist/host/blocksItems/handles.d.ts +10 -0
  136. package/dist/host/blocksItems/handles.d.ts.map +1 -0
  137. package/dist/host/blocksItems/handles.js +30 -0
  138. package/dist/host/blocksItems/handles.js.map +1 -0
  139. package/dist/host/blocksItems/implement.d.ts +22 -0
  140. package/dist/host/blocksItems/implement.d.ts.map +1 -0
  141. package/dist/host/blocksItems/implement.js +23 -0
  142. package/dist/host/blocksItems/implement.js.map +1 -0
  143. package/dist/host/blocksItems/itemExtras.d.ts +8 -0
  144. package/dist/host/blocksItems/itemExtras.d.ts.map +1 -0
  145. package/dist/host/blocksItems/itemExtras.js +106 -0
  146. package/dist/host/blocksItems/itemExtras.js.map +1 -0
  147. package/dist/host/blocksItems/itemLink.d.ts +12 -0
  148. package/dist/host/blocksItems/itemLink.d.ts.map +1 -0
  149. package/dist/host/blocksItems/itemLink.js +38 -0
  150. package/dist/host/blocksItems/itemLink.js.map +1 -0
  151. package/dist/host/blocksItems/items.d.ts +25 -0
  152. package/dist/host/blocksItems/items.d.ts.map +1 -0
  153. package/dist/host/blocksItems/items.js +427 -0
  154. package/dist/host/blocksItems/items.js.map +1 -0
  155. package/dist/host/blocksItems/tags.d.ts +24 -0
  156. package/dist/host/blocksItems/tags.d.ts.map +1 -0
  157. package/dist/host/blocksItems/tags.js +27 -0
  158. package/dist/host/blocksItems/tags.js.map +1 -0
  159. package/dist/host/blocksItems/types.d.ts +13 -0
  160. package/dist/host/blocksItems/types.d.ts.map +1 -0
  161. package/dist/host/blocksItems/types.js +83 -0
  162. package/dist/host/blocksItems/types.js.map +1 -0
  163. package/dist/host/blocksItems/volumes.d.ts +37 -0
  164. package/dist/host/blocksItems/volumes.d.ts.map +1 -0
  165. package/dist/host/blocksItems/volumes.js +361 -0
  166. package/dist/host/blocksItems/volumes.js.map +1 -0
  167. package/dist/host/coverage.d.ts +28 -0
  168. package/dist/host/coverage.d.ts.map +1 -0
  169. package/dist/host/coverage.js +45 -0
  170. package/dist/host/coverage.js.map +1 -0
  171. package/dist/host/customContent.d.ts +81 -0
  172. package/dist/host/customContent.d.ts.map +1 -0
  173. package/dist/host/customContent.js +213 -0
  174. package/dist/host/customContent.js.map +1 -0
  175. package/dist/host/debugUtilities.d.ts +192 -0
  176. package/dist/host/debugUtilities.d.ts.map +1 -0
  177. package/dist/host/debugUtilities.js +503 -0
  178. package/dist/host/debugUtilities.js.map +1 -0
  179. package/dist/host/entities/aimAssist.d.ts +11 -0
  180. package/dist/host/entities/aimAssist.d.ts.map +1 -0
  181. package/dist/host/entities/aimAssist.js +195 -0
  182. package/dist/host/entities/aimAssist.js.map +1 -0
  183. package/dist/host/entities/area.d.ts +14 -0
  184. package/dist/host/entities/area.d.ts.map +1 -0
  185. package/dist/host/entities/area.js +19 -0
  186. package/dist/host/entities/area.js.map +1 -0
  187. package/dist/host/entities/components.d.ts +61 -0
  188. package/dist/host/entities/components.d.ts.map +1 -0
  189. package/dist/host/entities/components.js +642 -0
  190. package/dist/host/entities/components.js.map +1 -0
  191. package/dist/host/entities/entityMembers.d.ts +35 -0
  192. package/dist/host/entities/entityMembers.d.ts.map +1 -0
  193. package/dist/host/entities/entityMembers.js +494 -0
  194. package/dist/host/entities/entityMembers.js.map +1 -0
  195. package/dist/host/entities/playerMembers.d.ts +23 -0
  196. package/dist/host/entities/playerMembers.d.ts.map +1 -0
  197. package/dist/host/entities/playerMembers.js +576 -0
  198. package/dist/host/entities/playerMembers.js.map +1 -0
  199. package/dist/host/entities/world.d.ts +315 -0
  200. package/dist/host/entities/world.d.ts.map +1 -0
  201. package/dist/host/entities/world.js +0 -0
  202. package/dist/host/events/componentEvents.d.ts +11 -0
  203. package/dist/host/events/componentEvents.d.ts.map +1 -0
  204. package/dist/host/events/componentEvents.js +23 -0
  205. package/dist/host/events/componentEvents.js.map +1 -0
  206. package/dist/host/events/eventOptions.d.ts +14 -0
  207. package/dist/host/events/eventOptions.d.ts.map +1 -0
  208. package/dist/host/events/eventOptions.js +224 -0
  209. package/dist/host/events/eventOptions.js.map +1 -0
  210. package/dist/host/events/eventValues.d.ts +41 -0
  211. package/dist/host/events/eventValues.d.ts.map +1 -0
  212. package/dist/host/events/eventValues.js +89 -0
  213. package/dist/host/events/eventValues.js.map +1 -0
  214. package/dist/host/events/worldEvents.d.ts +30 -0
  215. package/dist/host/events/worldEvents.d.ts.map +1 -0
  216. package/dist/host/events/worldEvents.js +207 -0
  217. package/dist/host/events/worldEvents.js.map +1 -0
  218. package/dist/host/formJson.d.ts +35 -0
  219. package/dist/host/formJson.d.ts.map +1 -0
  220. package/dist/host/formJson.js +84 -0
  221. package/dist/host/formJson.js.map +1 -0
  222. package/dist/host/formKit.d.ts +40 -0
  223. package/dist/host/formKit.d.ts.map +1 -0
  224. package/dist/host/formKit.js +124 -0
  225. package/dist/host/formKit.js.map +1 -0
  226. package/dist/host/forms.d.ts +92 -0
  227. package/dist/host/forms.d.ts.map +1 -0
  228. package/dist/host/forms.js +361 -0
  229. package/dist/host/forms.js.map +1 -0
  230. package/dist/host/gametest.d.ts +202 -0
  231. package/dist/host/gametest.d.ts.map +1 -0
  232. package/dist/host/gametest.js +316 -0
  233. package/dist/host/gametest.js.map +1 -0
  234. package/dist/host/inputs.d.ts +29 -0
  235. package/dist/host/inputs.d.ts.map +1 -0
  236. package/dist/host/inputs.js +110 -0
  237. package/dist/host/inputs.js.map +1 -0
  238. package/dist/host/jobs.d.ts +48 -0
  239. package/dist/host/jobs.d.ts.map +1 -0
  240. package/dist/host/jobs.js +62 -0
  241. package/dist/host/jobs.js.map +1 -0
  242. package/dist/host/jsprismarineServer.d.ts +65 -0
  243. package/dist/host/jsprismarineServer.d.ts.map +1 -0
  244. package/dist/host/jsprismarineServer.js +83 -0
  245. package/dist/host/jsprismarineServer.js.map +1 -0
  246. package/dist/host/minecraftServer.d.ts +229 -0
  247. package/dist/host/minecraftServer.d.ts.map +1 -0
  248. package/dist/host/minecraftServer.js +304 -0
  249. package/dist/host/minecraftServer.js.map +1 -0
  250. package/dist/host/minecraftServerUi.d.ts +30 -0
  251. package/dist/host/minecraftServerUi.d.ts.map +1 -0
  252. package/dist/host/minecraftServerUi.js +89 -0
  253. package/dist/host/minecraftServerUi.js.map +1 -0
  254. package/dist/host/netKit.d.ts +44 -0
  255. package/dist/host/netKit.d.ts.map +1 -0
  256. package/dist/host/netKit.js +87 -0
  257. package/dist/host/netKit.js.map +1 -0
  258. package/dist/host/pack.d.ts +71 -0
  259. package/dist/host/pack.d.ts.map +1 -0
  260. package/dist/host/pack.js +157 -0
  261. package/dist/host/pack.js.map +1 -0
  262. package/dist/host/serverAdmin.d.ts +44 -0
  263. package/dist/host/serverAdmin.d.ts.map +1 -0
  264. package/dist/host/serverAdmin.js +96 -0
  265. package/dist/host/serverAdmin.js.map +1 -0
  266. package/dist/host/serverBlocks.d.ts +32 -0
  267. package/dist/host/serverBlocks.d.ts.map +1 -0
  268. package/dist/host/serverBlocks.js +93 -0
  269. package/dist/host/serverBlocks.js.map +1 -0
  270. package/dist/host/serverComponents.d.ts +46 -0
  271. package/dist/host/serverComponents.d.ts.map +1 -0
  272. package/dist/host/serverComponents.js +297 -0
  273. package/dist/host/serverComponents.js.map +1 -0
  274. package/dist/host/serverCustom.d.ts +16 -0
  275. package/dist/host/serverCustom.d.ts.map +1 -0
  276. package/dist/host/serverCustom.js +161 -0
  277. package/dist/host/serverCustom.js.map +1 -0
  278. package/dist/host/serverEntities.d.ts +49 -0
  279. package/dist/host/serverEntities.d.ts.map +1 -0
  280. package/dist/host/serverEntities.js +358 -0
  281. package/dist/host/serverEntities.js.map +1 -0
  282. package/dist/host/serverFeedback.d.ts +15 -0
  283. package/dist/host/serverFeedback.d.ts.map +1 -0
  284. package/dist/host/serverFeedback.js +413 -0
  285. package/dist/host/serverFeedback.js.map +1 -0
  286. package/dist/host/serverGametest.d.ts +43 -0
  287. package/dist/host/serverGametest.d.ts.map +1 -0
  288. package/dist/host/serverGametest.js +246 -0
  289. package/dist/host/serverGametest.js.map +1 -0
  290. package/dist/host/serverItems.d.ts +17 -0
  291. package/dist/host/serverItems.d.ts.map +1 -0
  292. package/dist/host/serverItems.js +71 -0
  293. package/dist/host/serverItems.js.map +1 -0
  294. package/dist/host/serverNet.d.ts +41 -0
  295. package/dist/host/serverNet.d.ts.map +1 -0
  296. package/dist/host/serverNet.js +289 -0
  297. package/dist/host/serverNet.js.map +1 -0
  298. package/dist/host/serverObjects.d.ts +142 -0
  299. package/dist/host/serverObjects.d.ts.map +1 -0
  300. package/dist/host/serverObjects.js +326 -0
  301. package/dist/host/serverObjects.js.map +1 -0
  302. package/dist/host/serverProperties.d.ts +48 -0
  303. package/dist/host/serverProperties.d.ts.map +1 -0
  304. package/dist/host/serverProperties.js +193 -0
  305. package/dist/host/serverProperties.js.map +1 -0
  306. package/dist/host/serverScoreboard.d.ts +9 -0
  307. package/dist/host/serverScoreboard.d.ts.map +1 -0
  308. package/dist/host/serverScoreboard.js +198 -0
  309. package/dist/host/serverScoreboard.js.map +1 -0
  310. package/dist/host/serverStructures.d.ts +9 -0
  311. package/dist/host/serverStructures.d.ts.map +1 -0
  312. package/dist/host/serverStructures.js +243 -0
  313. package/dist/host/serverStructures.js.map +1 -0
  314. package/dist/host/tasks.d.ts +66 -0
  315. package/dist/host/tasks.d.ts.map +1 -0
  316. package/dist/host/tasks.js +107 -0
  317. package/dist/host/tasks.js.map +1 -0
  318. package/dist/host/world.d.ts +1359 -0
  319. package/dist/host/world.d.ts.map +1 -0
  320. package/dist/host/world.js +10 -0
  321. package/dist/host/world.js.map +1 -0
  322. package/dist/host/worldsystem/gameRules.d.ts +189 -0
  323. package/dist/host/worldsystem/gameRules.d.ts.map +1 -0
  324. package/dist/host/worldsystem/gameRules.js +86 -0
  325. package/dist/host/worldsystem/gameRules.js.map +1 -0
  326. package/dist/host/worldsystem/memoryWorldSystem.d.ts +18 -0
  327. package/dist/host/worldsystem/memoryWorldSystem.d.ts.map +1 -0
  328. package/dist/host/worldsystem/memoryWorldSystem.js +223 -0
  329. package/dist/host/worldsystem/memoryWorldSystem.js.map +1 -0
  330. package/dist/host/worldsystem/seam.d.ts +163 -0
  331. package/dist/host/worldsystem/seam.d.ts.map +1 -0
  332. package/dist/host/worldsystem/seam.js +0 -0
  333. package/dist/host/worldsystem/serverClocks.d.ts +18 -0
  334. package/dist/host/worldsystem/serverClocks.d.ts.map +1 -0
  335. package/dist/host/worldsystem/serverClocks.js +166 -0
  336. package/dist/host/worldsystem/serverClocks.js.map +1 -0
  337. package/dist/host/worldsystem/serverDimension.d.ts +10 -0
  338. package/dist/host/worldsystem/serverDimension.d.ts.map +1 -0
  339. package/dist/host/worldsystem/serverDimension.js +388 -0
  340. package/dist/host/worldsystem/serverDimension.js.map +1 -0
  341. package/dist/host/worldsystem/serverFog.d.ts +15 -0
  342. package/dist/host/worldsystem/serverFog.d.ts.map +1 -0
  343. package/dist/host/worldsystem/serverFog.js +66 -0
  344. package/dist/host/worldsystem/serverFog.js.map +1 -0
  345. package/dist/host/worldsystem/serverLoot.d.ts +9 -0
  346. package/dist/host/worldsystem/serverLoot.d.ts.map +1 -0
  347. package/dist/host/worldsystem/serverLoot.js +255 -0
  348. package/dist/host/worldsystem/serverLoot.js.map +1 -0
  349. package/dist/host/worldsystem/serverPrimitiveShapes.d.ts +9 -0
  350. package/dist/host/worldsystem/serverPrimitiveShapes.d.ts.map +1 -0
  351. package/dist/host/worldsystem/serverPrimitiveShapes.js +149 -0
  352. package/dist/host/worldsystem/serverPrimitiveShapes.js.map +1 -0
  353. package/dist/host/worldsystem/serverTickingAreas.d.ts +11 -0
  354. package/dist/host/worldsystem/serverTickingAreas.d.ts.map +1 -0
  355. package/dist/host/worldsystem/serverTickingAreas.js +176 -0
  356. package/dist/host/worldsystem/serverTickingAreas.js.map +1 -0
  357. package/dist/host/worldsystem/serverVolumes.d.ts +9 -0
  358. package/dist/host/worldsystem/serverVolumes.d.ts.map +1 -0
  359. package/dist/host/worldsystem/serverVolumes.js +248 -0
  360. package/dist/host/worldsystem/serverVolumes.js.map +1 -0
  361. package/dist/host/worldsystem/serverWorld.d.ts +18 -0
  362. package/dist/host/worldsystem/serverWorld.d.ts.map +1 -0
  363. package/dist/host/worldsystem/serverWorld.js +199 -0
  364. package/dist/host/worldsystem/serverWorld.js.map +1 -0
  365. package/dist/host/worldsystem/tags.d.ts +40 -0
  366. package/dist/host/worldsystem/tags.d.ts.map +1 -0
  367. package/dist/host/worldsystem/tags.js +43 -0
  368. package/dist/host/worldsystem/tags.js.map +1 -0
  369. package/dist/install.d.ts +39 -0
  370. package/dist/install.d.ts.map +1 -0
  371. package/dist/install.js +83 -0
  372. package/dist/install.js.map +1 -0
  373. package/dist/isRecord.d.ts +3 -0
  374. package/dist/isRecord.d.ts.map +1 -0
  375. package/dist/isRecord.js +6 -0
  376. package/dist/isRecord.js.map +1 -0
  377. package/dist/library.d.ts +40 -0
  378. package/dist/library.d.ts.map +1 -0
  379. package/dist/library.js +101 -0
  380. package/dist/library.js.map +1 -0
  381. package/dist/manifest.d.ts +37 -0
  382. package/dist/manifest.d.ts.map +1 -0
  383. package/dist/manifest.js +40 -0
  384. package/dist/manifest.js.map +1 -0
  385. package/dist/native/manifest.json.js +45 -0
  386. package/dist/native/manifest.json.js.map +1 -0
  387. package/dist/nativeHash.d.ts +16 -0
  388. package/dist/nativeHash.d.ts.map +1 -0
  389. package/dist/nativeHash.js +52 -0
  390. package/dist/nativeHash.js.map +1 -0
  391. package/dist/platform.d.ts +50 -0
  392. package/dist/platform.d.ts.map +1 -0
  393. package/dist/platform.js +77 -0
  394. package/dist/platform.js.map +1 -0
  395. package/dist/shape/binding.d.ts +112 -0
  396. package/dist/shape/binding.d.ts.map +1 -0
  397. package/dist/shape/binding.js +558 -0
  398. package/dist/shape/binding.js.map +1 -0
  399. package/dist/shape/engineRuntime.d.ts +55 -0
  400. package/dist/shape/engineRuntime.d.ts.map +1 -0
  401. package/dist/shape/engineRuntime.js +451 -0
  402. package/dist/shape/engineRuntime.js.map +1 -0
  403. package/dist/shape/format.d.ts +249 -0
  404. package/dist/shape/format.d.ts.map +1 -0
  405. package/dist/shape/format.js +43 -0
  406. package/dist/shape/format.js.map +1 -0
  407. package/dist/shape/history.d.ts +24 -0
  408. package/dist/shape/history.d.ts.map +1 -0
  409. package/dist/shape/history.js +65 -0
  410. package/dist/shape/history.js.map +1 -0
  411. package/dist/shape/implementations.d.ts +105 -0
  412. package/dist/shape/implementations.d.ts.map +1 -0
  413. package/dist/shape/implementations.js +62 -0
  414. package/dist/shape/implementations.js.map +1 -0
  415. package/dist/shape/plan.d.ts +138 -0
  416. package/dist/shape/plan.d.ts.map +1 -0
  417. package/dist/shape/plan.js +0 -0
  418. package/dist/shape/resolve.d.ts +56 -0
  419. package/dist/shape/resolve.d.ts.map +1 -0
  420. package/dist/shape/resolve.js +78 -0
  421. package/dist/shape/resolve.js.map +1 -0
  422. package/dist/shape/version.d.ts +15 -0
  423. package/dist/shape/version.d.ts.map +1 -0
  424. package/dist/shape/version.js +35 -0
  425. package/dist/shape/version.js.map +1 -0
  426. package/dist/testing/debuggerWorker.d.ts +15 -0
  427. package/dist/testing/debuggerWorker.d.ts.map +1 -0
  428. package/dist/testing/debuggerWorker.js +29 -0
  429. package/dist/testing/debuggerWorker.js.map +1 -0
  430. package/dist/testing/engineWorker.d.ts +7 -0
  431. package/dist/testing/engineWorker.d.ts.map +1 -0
  432. package/dist/testing/engineWorker.js +31 -0
  433. package/dist/testing/engineWorker.js.map +1 -0
  434. package/dist/values.d.ts +94 -0
  435. package/dist/values.d.ts.map +1 -0
  436. package/dist/values.js +204 -0
  437. package/dist/values.js.map +1 -0
  438. package/native/manifest.json +49 -0
  439. package/package.json +177 -6
  440. package/scripts/postinstall.mjs +54 -0
package/README.md CHANGED
@@ -1,45 +1,684 @@
1
1
  # @jsprismarine/script-host
2
2
 
3
- ## ⚠️ IMPORTANT NOTICE ⚠️
3
+ [![Join the Discord Server](https://img.shields.io/discord/704967868885762108?color=%237289DA&label=Discord)](https://discord.gg/kZZCDyCBbW)
4
+ [![npm](https://img.shields.io/npm/dt/@jsprismarine/script-host)](https://www.npmjs.com/package/@jsprismarine/script-host)
4
5
 
5
- **This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
6
+ The engine JSPrismarine runs Bedrock behavior pack scripts in. It holds one native library, Fabrice
7
+ Bellard's [QuickJS](https://bellard.org/quickjs/) with a small C layer of our own, and the
8
+ TypeScript that binds it through `node:ffi`. Each world will own one engine and run it on its own
9
+ thread, as [ADR 0020](../../docs/adr/0020-scripts-run-in-quickjs-on-the-world-thread.md) decides.
10
+ The plan that builds the rest of the script host on top of this package is
11
+ [script-api-host.md](../../docs/plans/script-api-host.md).
6
12
 
7
- This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
13
+ This release has the engine, with evaluation, host calls, limits and the sandbox; the shape of the
14
+ Script API, every module, class and member of `@minecraft/server` and the other modules, stable and
15
+ beta, generated from Mojang's metadata; and the runtime that loads a world's behavior packs and runs
16
+ their scripts, with the first members that have behavior.
8
17
 
9
- ## Purpose
18
+ ## Installing
10
19
 
11
- This package exists to:
12
- 1. Configure OIDC trusted publishing for the package name `@jsprismarine/script-host`
13
- 2. Enable secure, token-less publishing from CI/CD workflows
14
- 3. Establish provenance for packages published under this name
20
+ ```bash
21
+ npm install @jsprismarine/script-host
22
+ ```
15
23
 
16
- ## What is OIDC Trusted Publishing?
24
+ The package holds no native code. Its install script downloads the library's build for the
25
+ machine from the project's GitHub releases, checks its SHA-256 against `native/manifest.json`, and
26
+ writes it to `prebuilds/<platform>/`. Loading the library downloads nothing. Builds exist for
27
+ <!-- fact:scripting.buildPlatforms -->macOS on Apple silicon, Linux on arm64 with glibc, Linux on arm64 with musl, Linux on x64 with glibc, Linux on x64 with musl and Windows on x64<!-- /fact -->.
17
28
 
18
- OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
29
+ npm 12, pnpm and Bun run a dependency's install script only once the project approves it. Until
30
+ then, loading the library throws a `NativeLibraryError` that names the command for each:
31
+ `npm install-scripts approve @jsprismarine/script-host`, `pnpm approve-builds`, or
32
+ `trustedDependencies` in Bun's `package.json`. Set `JSP_SCRIPT_HOST_LIBRARY` to a library file to
33
+ load it instead; the file must be the published build or a local build. [Building it](#building-it)
34
+ covers a local build.
19
35
 
20
- ## Setup Instructions
36
+ ## Running a script
21
37
 
22
- To properly configure OIDC trusted publishing for this package:
38
+ ```ts
39
+ import { ScriptHostLibrary } from '@jsprismarine/script-host';
23
40
 
24
- 1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
25
- 2. Configure the trusted publisher (e.g., GitHub Actions)
26
- 3. Specify the repository and workflow that should be allowed to publish
27
- 4. Use the configured workflow to publish your actual package
41
+ const library = ScriptHostLibrary.load();
42
+ const engine = library.createEngine({ memoryLimit: 64 * 1024 * 1024 });
28
43
 
29
- ## DO NOT USE THIS PACKAGE
44
+ try {
45
+ engine.defineGlobalFunction('add', (a, b) => Number(a) + Number(b));
46
+ engine.evaluate('add(1, 2)'); // 3
30
47
 
31
- This package is a placeholder for OIDC configuration only. It:
32
- - Contains no executable code
33
- - Provides no functionality
34
- - Should not be installed as a dependency
35
- - Exists only for administrative purposes
48
+ engine.setBudget({ perCallback: 1000 });
49
+ engine.evaluate('while (true) {}'); // throws ScriptTerminatedError
50
+ } finally {
51
+ engine.destroy();
52
+ }
53
+ ```
36
54
 
37
- ## More Information
55
+ An engine runs only on the thread that created it, and every call into it is synchronous. Engines
56
+ on different threads share nothing, so two worlds on two worker threads each run their own.
38
57
 
39
- For more details about npm's trusted publishing feature, see:
40
- - [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
41
- - [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
58
+ Primitive values cross between TypeScript and a script as copies. Objects and functions stay in
59
+ the engine, and the host holds a `ScriptHandle` to each one it receives. A handle that a call
60
+ returns belongs to the caller, who frees it with `engine.free`. A handle passed to a host function
61
+ lasts until that function returns; `engine.duplicate` makes one that outlives it. A host function
62
+ that makes an object to return passes it through `engine.release`, which frees the handle once the
63
+ script has the object.
42
64
 
43
- ---
65
+ ## How it is called
44
66
 
45
- **Maintained for OIDC setup purposes only**
67
+ The library has a flat C interface, `native/include/jsp_script_host.h`, with an ABI version the
68
+ binding checks when it loads. It passes only integers, doubles and pointers, so the same interface
69
+ fits `node:ffi` today and scriptc's FFI later
70
+ ([ADR 0023](../../docs/adr/0023-quickjs-through-one-c-layer-and-ffi.md)).
71
+
72
+ Values cross as bytes in a transfer buffer, a `SharedArrayBuffer` that the engine writes and reads
73
+ in place. A host call from a script is one crossing: the engine writes the arguments into the
74
+ buffer and calls the engine's one `node:ffi` callback with the host function's id. The callback
75
+ runs the TypeScript function on the same thread and writes the result into the same buffer. A host
76
+ function may call back into the script it serves. The engine counts host calls and the bytes each
77
+ way, which `engine.stats()` reports.
78
+
79
+ Module imports go through the same callback: `createEngine({ loadModule })` returns a module's
80
+ source for its name, or an object whose own enumerable properties become the module's exports.
81
+
82
+ ## Contexts
83
+
84
+ An engine can hold several contexts, each with a global object and built-ins of its own, so packs
85
+ in one world never share a `globalThis` while they share one runtime, one step budget and one
86
+ memory limit. `engine.createContext()` makes one, and `engine.inContext(id, run)` runs host code
87
+ with it current. While a script calls the host, the caller's context is current, and the module
88
+ loader is told which context imports. `engine.runJobs(id)` runs one context's promise jobs and
89
+ leaves the other contexts' jobs queued in their order, which the version 1 and version 2
90
+ lifecycles need.
91
+
92
+ ## Limits
93
+
94
+ Every limit counts work, not time, so a script stops at the same point on every machine and in
95
+ every replay ([ADR 0021](../../docs/adr/0021-the-script-watchdog-counts-steps.md)).
96
+
97
+ - **Steps.** QuickJS polls for interrupts at backward jumps and calls, and calls its interrupt
98
+ handler once every `JS_INTERRUPT_COUNTER_INIT` polls, a constant in `quickjs.c`. Each handler call
99
+ is a step. `engine.setBudget` sets how many
100
+ steps one call from the host may take, counting everything it calls, and how many one tick may
101
+ take, counted from `engine.beginTick()`. The step past a budget throws an error no script can
102
+ catch, and the call throws `ScriptTerminatedError`. Each call from the host counts its steps from
103
+ zero, so earlier calls do not move where a later one stops.
104
+ - **Memory.** `memoryLimit` caps the bytes the engine allocates. An allocation past it fails, the
105
+ engine counts the refusal, and an error that reaches the host throws `ScriptOutOfMemoryError`.
106
+ - **Stack.** `stackSize` sets the native stack a script may use, `DEFAULT_STACK_SIZE` unless set.
107
+ Past it, the script gets `InternalError: stack overflow`, as on Bedrock Dedicated Server (BDS).
108
+ The engine counts every overflow, including one a script catches, because BDS treats a caught
109
+ overflow as critical too.
110
+
111
+ The errors the host throws, such as `ScriptError`, `ScriptTerminatedError` and
112
+ `NativeLibraryError`, come from `@jsprismarine/errors/script-host`. Its
113
+ [error reference](../../docs/errors/script-host.md) lists each one's code and cause.
114
+
115
+ ## The sandbox
116
+
117
+ A script sees only what the host gives it: no Node.js API, no filesystem and no network. Each new
118
+ context also matches the language that BDS's older QuickJS offers. The `globals` scenario of the
119
+ parity suite's `scripting.engine` family records that language on the pinned BDS: every global
120
+ name, the own keys of every built-in and its prototype, and the errors below. Its row compares the
121
+ engine with that record.
122
+
123
+ - The C layer deletes every global and member listed in `src/absentGlobals.ts`, such as `eval`,
124
+ `Iterator` and its helpers, `Float16Array`, `Atomics`, the newer `Set` methods, resizable
125
+ `ArrayBuffer`, the `Uint8Array` base64 and hex methods and `Map.prototype.getOrInsert`. The list
126
+ holds exactly what the pinned QuickJS defines and BDS lacks. The native build writes it into a C
127
+ header, so the list exists once.
128
+ - It adds `Object.__getClass` and `String.prototype.__quote`, which BDS's older QuickJS has.
129
+ - `eval` is not defined, so calling it throws `ReferenceError: 'eval' is not defined`.
130
+ - `Function`, and the generator and async function constructors, throw
131
+ `TypeError: Function from string is not supported` instead of compiling a string.
132
+ - A regular expression with the `v` flag, a modifier group such as `(?i:a)` or a group name used
133
+ twice throws the `SyntaxError` BDS throws, in a literal or through `RegExp`.
134
+
135
+ ## The Script API's shape
136
+
137
+ The modules a pack imports, such as `@minecraft/server`, are generated rather than written by hand
138
+ ([ADR 0022](../../docs/adr/0022-the-script-api-surface-is-generated.md)). `generate:shape` reads
139
+ `metadata/script_modules` from the `bedrock-samples` checkout that
140
+ `packages/bedrock-data/sources.json` pins, and writes one file per module to
141
+ `src/generated/script-modules/`. Each file keeps every version of its module as history, the beta
142
+ the pinned metadata ships included, such as `@minecraft/server`
143
+ <!-- fact:scripting.serverBeta -->2.12.0-beta<!-- /fact -->. A
144
+ class or member is a list of segments, each with the first version it appears in and, once Mojang
145
+ removes or changes it, the last. A regeneration after a version bump therefore shows each added,
146
+ changed or removed member as its own line in the diff.
147
+
148
+ ```sh
149
+ pnpm --filter @jsprismarine/script-host run generate:shape # fetches the checkout if needed
150
+ pnpm --filter @jsprismarine/script-host run check:shape # fails when src/generated is stale
151
+ ```
152
+
153
+ The metadata has gaps, such as the privilege `CustomCommandRegistry.registerCommand`'s callback
154
+ runs under. `scripts/shape/overrides.mts` fills them, each with its evidence, and the generator fails
155
+ once the metadata records a value of its own, so a stale override cannot linger.
156
+
157
+ A pack gets the newest stable minor version of the major version it declares, as on Bedrock
158
+ Dedicated Server, so a pack that declares 2.0.0 sees every 2.x member the pinned server ships. Beta
159
+ versions do not follow semver. With the world's Beta APIs experiment on, a pack that declares a
160
+ beta gets it only when it is the one beta the pinned server ships, such as `@minecraft/server`
161
+ <!-- fact:scripting.serverBeta -->2.12.0-beta<!-- /fact -->, and the version `beta` names that one.
162
+ Any other version, beta or stable, is refused, as an older or newer beta is on BDS. `resolveDependency` does that resolution, and returns BDS's own content
163
+ log message when it refuses a module.
164
+
165
+ ```ts
166
+ import { ScriptHostLibrary } from '@jsprismarine/script-host';
167
+ import { ScriptApiContext } from '@jsprismarine/script-host/shape/binding';
168
+ import { ScriptApiImplementations } from '@jsprismarine/script-host/shape/implementations';
169
+ import { resolveDependency } from '@jsprismarine/script-host/shape/resolve';
170
+
171
+ const resolution = resolveDependency(
172
+ { module_name: '@minecraft/server', version: '2.0.0' },
173
+ { pack: { name: 'my pack', version: '1.0.0' }, allowedModules: ['@minecraft/server'] }
174
+ );
175
+
176
+ const implementations = new ScriptApiImplementations().implement(
177
+ '@minecraft/server',
178
+ 'World',
179
+ 'getDimension',
180
+ (call) => `the ${call.args[0]} dimension`
181
+ );
182
+ const engine = ScriptHostLibrary.load().createEngine();
183
+ const context = new ScriptApiContext(engine, { pack: 'my pack - 1.0.0', implementations, logger: console });
184
+ try {
185
+ // A namespace handle. A script's import reaches it only through the engine's `loadModule`.
186
+ if (resolution.ok) context.bind(resolution.shape);
187
+ } finally {
188
+ context.destroy();
189
+ engine.destroy();
190
+ }
191
+ ```
192
+
193
+ `ScriptApiContext` installs a module into a namespace object with every class, enum, constant and
194
+ error class the served version has. Every member is present, so `typeof world.sendMessage` and other
195
+ feature tests see what they see on BDS. Before anything else runs, a member checks its arguments
196
+ against the metadata and throws a `TypeError` or an `ArgumentOutOfBoundsError` worded the way BDS
197
+ words them, as the `argument-errors` scenario of the parity suite records them. An instance member
198
+ called on an object the host did not make throws BDS's `object bound to prototype does not exist`
199
+ error. With a `privilege` option, a member whose metadata does not list the privilege the running
200
+ script has, such as early or restricted execution, throws BDS's `cannot be used in` error. Then it calls the implementation registered for its module, class and member. A member with none throws `NotImplementedError`, which names the module, the class
201
+ and the member, and the context logs it the first time each pack uses it.
202
+
203
+ `implement` takes the names the generated `ScriptApiMembers` lists, so a misspelled member does not
204
+ compile, and the form a member needs: a function for a method or constructor, `{ get }` for a
205
+ read-only property and `{ get, set }` for a writable one. An implementation throws one of the API's
206
+ own error classes, such as `LocationInUnloadedChunkError`, by throwing a `ScriptApiError`.
207
+
208
+ An object the host makes with `context.create(module, className, tag, state)` carries a number and
209
+ a string, which every call of its members receives as `call.tag` and `call.state`: an entity's id,
210
+ or an item stack's contents. The state lives in the engine for as long as the object does, so the
211
+ host keeps no table that a script's garbage would grow. `call.setState` replaces it, and a
212
+ constructor's implementation returns the new object's state. A member whose metadata returns plain
213
+ data, an interface such as `Vector3` or an array such as `string[]`, returns it as one JSON string,
214
+ and the binding parses it inside the engine, so `entity.location` costs one host call.
215
+
216
+ ## The add-on corpus
217
+
218
+ The order in which members get behavior comes from what real add-ons use. `corpus/packs.json` pins
219
+ open-source behavior packs with scripts: each repository by its GitHub URL, a full commit hash, the
220
+ sha256 of GitHub's zip of that commit, and its license. Only permissive licenses such as MIT and
221
+ Apache-2.0 are accepted, and `scripts/corpus/manifest.mts` lists them. The file also records the
222
+ candidates the corpus leaves out and why. The repository holds no copy of any add-on.
223
+
224
+ ```sh
225
+ pnpm --filter @jsprismarine/script-host run count:corpus # fetches what is missing, then counts
226
+ pnpm --filter @jsprismarine/script-host run check:corpus # fails when the counts are stale
227
+ ```
228
+
229
+ `count:corpus` downloads each pinned commit into `node_modules/.cache/jsprismarine/addon-corpus/`
230
+ through `@jsprismarine/bedrock-data`'s fetch, which checks the digest before unpacking anything, and
231
+ reuses the cached copy after that. A commit that no longer exists upstream fails with HTTP 404 and an
232
+ error naming the packs it holds. The counter then reads each pack's `manifest.json` for the modules
233
+ and versions it declares, and walks its scripts. It writes two files beside the manifest:
234
+ `corpus/usage.json`, every pack's uses with one key per line, and `corpus/ranking.md`, the modules,
235
+ declarations, events, members and interface fields ordered by how many packs use them, split by
236
+ whether the pack declares the module as stable or beta.
237
+
238
+ The counter reads a TypeScript pack from its TypeScript sources and never runs its build. A build
239
+ would mean installing the pack's npm dependencies and running its scripts, and the bundle it makes
240
+ mixes the pack's code with the libraries it bundles. The sources also carry type annotations, which
241
+ tell the counter what a value is. A pack's `build` field in the manifest says what its build step
242
+ would do. Libraries a pack bundles from npm, such as `@minecraft/math`, are not counted.
243
+
244
+ The counter parses each file with oxc and follows values through the generated shape: from an
245
+ import, through property types and method return types, `await`, array elements and destructuring,
246
+ into a callback whose parameters the shape types, and from `getComponent('minecraft:inventory')` to
247
+ `EntityInventoryComponent`. It counts a member on the class that declares it, so `player.kill()`
248
+ counts as `Entity.kill`. A value it cannot follow, such as one passed in from another file, goes
249
+ uncounted, so the counts are a lower bound. A member a pack adds to an API type through
250
+ `declare module` is the pack's own and is not counted. A beta pack resolves against the beta the
251
+ pinned server ships when that beta has the pack's major version, whichever beta the pack names,
252
+ since BDS serves only that one. A beta of another major version resolves against the newest
253
+ stable version of its own major version.
254
+
255
+ `scripts/corpus/corpus.test.mts` checks the counts against the corpus when every pinned repository
256
+ is already cached, and skips otherwise, so an ordinary test run needs no network. Set
257
+ `JSP_ADDON_CORPUS_TESTS=1` to fetch what is missing and run it anyway.
258
+
259
+ ## The debugger
260
+
261
+ `engine.attachDebugger(listener)` attaches a debugger to an engine. From then on, every function
262
+ the engine enters reports each new line, and the engine stops the script at a breakpoint, after a
263
+ step, on a pause request, and, when asked, on every value the script throws. A stop calls
264
+ `listener.paused(reason)` on the engine's thread, inside the engine call that ran the script, so
265
+ that call, and the world tick that made it, stays blocked until the listener returns. Before it
266
+ returns, the listener reads the stopped script and calls `resume` with `continue`, `stepOver`,
267
+ `stepIn` or `stepOut`.
268
+
269
+ ```ts
270
+ import { ScriptHandle } from '@jsprismarine/script-host/values';
271
+
272
+ const debug = engine.attachDebugger({
273
+ paused(reason) {
274
+ const [top] = debug.frames(); // { name, file, line, column }
275
+ const locals = debug.scope(0, 'local');
276
+ const { properties } = debug.properties(locals);
277
+ try {
278
+ console.log(reason, top, properties);
279
+ } finally {
280
+ // Each object among the values is a handle of its own, as the scope is.
281
+ for (const { value } of properties) if (value instanceof ScriptHandle) engine.free(value);
282
+ engine.free(locals);
283
+ }
284
+ debug.resume('stepOver');
285
+ return 'resume';
286
+ },
287
+ poll() {} // read the debugger's messages without waiting
288
+ });
289
+ debug.setBreakpoints('main.js', [12]);
290
+ ```
291
+
292
+ Nothing reads a clock. A script stops at the same line on every run, a running script calls
293
+ `poll` once every `pollLines` lines (`DEFAULT_POLL_LINES` unless set) so a debugger can pause a
294
+ loop that never ends, and stopping costs no steps. `evaluate(frame, source)` runs source with
295
+ a frame's variables in scope and writes through to them. It gets its own budget of
296
+ `JSH_DEBUG_EVALUATE_STEPS` steps, and the stopped script keeps its step counts. `describe` and
297
+ `properties` read values without running a getter or a proxy's handler. A replay never attaches
298
+ a debugger. Functions already running when a debugger attaches do not report lines, so attach
299
+ between calls into the engine.
300
+
301
+ ### The VS Code extension's protocol
302
+
303
+ `src/debugger/` speaks the protocol of Mojang's Minecraft Bedrock Debugger for VS Code
304
+ (`Mojang/minecraft-debugger`), at version `DEBUGGER_PROTOCOL_VERSION`, so the extension attaches
305
+ to JSPrismarine as it attaches to Bedrock Dedicated Server (BDS). The work splits across two
306
+ threads, because a stopped script blocks the thread its engine runs on, and that thread cannot
307
+ read a socket while the extension inspects the script:
308
+
309
+ - `DebuggerThread` (`./debugger/thread`) starts a worker that owns the sockets. Its `listen`
310
+ waits for the extension (the extension's `connect` mode, `/script debugger listen`) and its
311
+ `connect` reaches one that listens (its `listen` mode, `/script debugger connect`). Both
312
+ default to `DEFAULT_DEBUGGER_PORT`, and each closes the listener and connection the thread
313
+ held before. A listener on an address other than loopback needs a passcode, and refuses to
314
+ start without one with BDS's message. The worker frames each message as its length in 8
315
+ hexadecimal digits, a newline, and the JSON with a newline after it, and it closes a
316
+ connection whose header states a body over `MAX_RECEIVED_FRAME_LENGTH` before the body
317
+ arrives. The worker does not keep the process alive.
318
+ - For each connection, the thread's `connected` event hands the starting thread a
319
+ `DebuggerChannelEndpoint`, with the extension's address and port. A `DebuggerChannelBridge`
320
+ in the worker feeds it, and `PortDebuggerChannel` reads it with `receiveMessageOnPort`,
321
+ waiting on a shared counter while a script is stopped, since the engine thread's event loop
322
+ does not run then. The `activity` event follows every message the extension sends and the
323
+ connection's close, so the engine's thread knows when to poll without a timer.
324
+ - `ScriptDebugSession` runs on the engine's thread. `offer` sends the protocol event, with the
325
+ passcode requirement and the packs, without waiting, and `handshake` checks the answer:
326
+ it refuses a wrong version, a wrong passcode or an unknown `targetModuleUUID` with BDS's
327
+ messages. A host that must not block on an extension that never answers calls `handshake`
328
+ only once a message has arrived. `attach` takes the engine and the context of the pack the
329
+ extension picked, which `WorldScripts.debugTarget` finds, and handles its breakpoints until
330
+ it sends `resume`. Only that context's scripts stop, so another pack's `scripts/main.js` never
331
+ hits a breakpoint set for this one. While a script is stopped, the session answers
332
+ `stackTrace`, `scopes`, `variables`, `evaluate`, `continue`, `next`, `stepIn`, `stepOut` and
333
+ `pause`, and `poll` handles what arrives between ticks. When the connection closes, at any of
334
+ these points, the session detaches from the engine, so a new debugger can attach.
335
+ - The session speaks the rest of the protocol as the pinned BDS does on the wire. A passed
336
+ handshake is followed by a `SchemaEvent` with BDS's diagnostics tabs (`DIAGNOSTICS_TABS`), and
337
+ `stats` sends a tick's `StatEvent2`. `detachEngine` sends `ThreadEvent` `exited` and keeps the
338
+ session open, as BDS does around `/reload`; the next `attach`, to the new engine, sends `new`
339
+ and sets the breakpoints and exception setting again without waiting for another `resume`.
340
+ `detach` sends `terminated` before the session ends, unless the handshake was refused. A
341
+ `minecraftCommand` goes to the `runCommand` option. `startProfiler` and `stopProfiler` record
342
+ the debugged pack's stack at each poll, every `pollLines` lines, and send it back as a
343
+ `ProfilerCapture` holding a `.cpuprofile`, so a script that runs fewer lines between ticks
344
+ than the poll interval leaves no samples.
345
+
346
+ ```ts
347
+ import { ScriptDebugSession } from '@jsprismarine/script-host/debugger/DebugSession';
348
+ import { PortDebuggerChannel } from '@jsprismarine/script-host/debugger/channel';
349
+ import { DebuggerThread } from '@jsprismarine/script-host/debugger/thread';
350
+
351
+ let session: ScriptDebugSession | undefined;
352
+ let attached = false;
353
+ const thread = new DebuggerThread({
354
+ connected({ endpoint }) {
355
+ session = new ScriptDebugSession(new PortDebuggerChannel(endpoint), { plugins, passcode });
356
+ session.offer();
357
+ },
358
+ activity() {
359
+ if (session === undefined) return;
360
+ if (attached) {
361
+ session.poll(); // between ticks
362
+ return;
363
+ }
364
+ const target = session.handshake(); // the script module UUID the extension picked
365
+ const picked = target === undefined ? undefined : worldScripts.debugTarget(target);
366
+ if (picked !== undefined) session.attach(picked.engine, picked.context);
367
+ attached = picked !== undefined;
368
+ }
369
+ });
370
+ await thread.listen({ port: 19144, address: '127.0.0.1', passcode });
371
+ // session.detach() and thread.close() for /script debugger close
372
+ ```
373
+
374
+ The sketch leaves out what JSPrismarine's world host adds: a peek at the channel, so `handshake`
375
+ never waits, BDS's refusal printed to the debug console, and an attach that waits for
376
+ `WorldScripts`' `onPackLoaded` when the picked pack has not loaded yet, which is how a debugger
377
+ attached at startup stops at a pack's first line, and that keeps the session across `/reload`.
378
+ The host does not implement the extension's `debugger-request` or `diagnostics-set-active`
379
+ messages yet. It answers a `debugger-request` as refused.
380
+
381
+ ## Running a world's scripts
382
+
383
+ `WorldScripts` is the script runtime of one world: one engine, a context for each pack, and the
384
+ lifecycle, system tasks, events and watchdog around them. It reaches the world only through
385
+ `ScriptWorld` (`@jsprismarine/script-host/host/world`), a narrow interface the server implements
386
+ with plain data: the dimensions, the players and entities by id, each read in one call, the blocks
387
+ and their permutations, the item types, commands, `sendMessage`, the weather and its guard, the
388
+ guard on the players' chat, the changes the world committed, and the clock the tick admitted. The
389
+ host imports no world class.
390
+
391
+ A script's `Entity` or `Block` is a handle: an object whose state names the entity's id or the
392
+ block's position, and whose members read the world each time they run. Once an entity is gone,
393
+ `isValid` is false, `id` and `typeId` still answer, and its other members throw BDS's
394
+ `InvalidEntityError`. A pack gets one object per entity, so `===` compares two. An item stack is a
395
+ value the script owns, held in its object's state. A pack's
396
+ dynamic properties on the world and on an entity live in the world, keyed by the pack's header
397
+ UUID, and a script writes them through `ScriptWorld.setDynamicProperties`; an item stack keeps
398
+ its own in its state, keyed by the script module UUID, as BDS keys them on disk. The scripts'
399
+ `world.scoreboard` is `ScriptWorld.scoreboard`, which the server shares with `/scoreboard`.
400
+ `src/testing/memoryWorld.test-utils.ts` is a `ScriptWorld`
401
+ in memory, which counts what the host reads, for tests that bound the world calls a member makes.
402
+
403
+ ```ts
404
+ import { readScriptConfig, readScriptPack } from '@jsprismarine/script-host/host/pack';
405
+ import { WorldScripts, watchdogSettings } from '@jsprismarine/script-host/host/WorldScripts';
406
+
407
+ const scripts = new WorldScripts({
408
+ library,
409
+ world, // a ScriptWorld
410
+ packs: directories.map(readScriptPack).filter((pack) => pack !== undefined),
411
+ config: readScriptConfig('config'), // BDS's config/ folder
412
+ log: console,
413
+ server: { version, minecraftVersion, protocolVersion }, // what @jsprismarine/server reports
414
+ seed: worldSeed,
415
+ watchdog: watchdogSettings({ 'script-watchdog-hang-threshold': '10000' }),
416
+ onShutdown: (reason) => server.stop()
417
+ });
418
+ scripts.startEarly(); // version 2 packs: top level, promise jobs once, startup
419
+ scripts.startWorld(); // version 1 packs, once the world has loaded: top level, worldInitialize
420
+ // at the end of every tick, before its change log closes:
421
+ scripts.flush();
422
+ ```
423
+
424
+ The order of everything matches the pinned BDS, as the `scripting.*` families of the parity suite
425
+ record it:
426
+
427
+ - **Packs.** `readScriptPack` reads a pack's manifest. A pack gets each native module it declares
428
+ at the newest stable minor of the declared major version, when `config/default/permissions.json`
429
+ or `config/<script module uuid>/permissions.json` allows the module, and otherwise logs BDS's
430
+ message and does not load. A beta version loads only when the `betaApis` option says the world
431
+ has the Beta APIs experiment on, as `resolveDependency` describes. For a module or version the
432
+ pinned server does not ship, the runtime logs BDS's `failed to create context` and, once every
433
+ pack of the lifecycle has loaded, `run failed`. A pack declaring `@minecraft/server` 1.x runs the version 1
434
+ lifecycle, any other the version 2 one. Each pack runs in a context of its own. An `import()`
435
+ of a module the manifest does not declare rejects as on BDS, except `@jsprismarine/server`,
436
+ which resolves, so a pack can detect JSPrismarine and fall back on BDS.
437
+ - **The flush.** `flush` runs the version 1 promise jobs once, then until nothing is left: the
438
+ version 2 promise jobs, the system tasks due, each followed by version 2 promise jobs, and the
439
+ after-events, each type followed by version 2 promise jobs. A `system.run` that a running task
440
+ queues waits for the next tick, which stops a task that queues itself from running for ever.
441
+ - **Privileges.** Top levels of version 2 packs, their first promise jobs and `startup` run in
442
+ early execution, before-events in restricted execution, and the rest with the default
443
+ privilege. A member whose metadata does not list the privilege throws BDS's error.
444
+ - **Inputs.** `Math.random` in each context draws from a generator seeded from the world's seed
445
+ and the pack's place, and `Date` reads `ScriptWorld.clock()`, so a replay runs the same.
446
+ - **The watchdog.** A callback that takes more than its step budget stops with an error no script
447
+ catches. `watchdogSettings` converts BDS's millisecond threshold at `STEPS_PER_MILLISECOND`. A
448
+ hang, a stack overflow, even a caught one, and an allocation past the memory limit are critical:
449
+ the runtime logs BDS's lines and, unless `script-watchdog-enable-shutdown` is `false`, stops and
450
+ calls `onShutdown`. Before it shuts down for a hang or a stack overflow, it sends the beta
451
+ `system.beforeEvents.watchdogTerminate`, and a script that cancels it keeps the server and its
452
+ packs running, as on BDS.
453
+ - **Chat.** `world.beforeEvents.chatSend`, a beta event, is a guard the runtime adds to the
454
+ world's chat action through `ScriptWorld.guardChat`. It runs in restricted execution while the
455
+ line is sent, and a cancel drops the line before anyone gets it.
456
+ - **Coverage.** When a pack loads, the runtime logs how many of the members its scripts name are
457
+ implemented, and which are not.
458
+ - **Reload.** `reload` sends `system.beforeEvents.shutdown`, then runs every pack again from its
459
+ top level, as BDS's `/reload` does. `system.currentTick` carries on.
460
+ - **Debugging.** `debugTarget` finds the engine and context of a loaded pack by its script module
461
+ UUID. The `onPackLoaded` option names each pack once its context is ready and before its top
462
+ level runs, so a debugger attached there stops at the pack's first line. `reload` replaces the
463
+ engine, so a debugger session detaches from the old one first and attaches to the new one
464
+ when `onPackLoaded` names its pack again.
465
+
466
+ ### Forms
467
+
468
+ A pack that declares `@minecraft/server-ui` gets `ActionFormData`, `ModalFormData`,
469
+ `MessageFormData`, their responses and `uiManager.closeAllForms`, in the version 1 and version 2
470
+ shapes and the beta. The data-driven `CustomForm`, `MessageBox` and observables throw
471
+ `NotImplementedError`. Forms reach the world through `ScriptWorld.forms`, a `ScriptFormChannel`
472
+ that sends a player a form, closes a player's forms, and hands back the answers the input step
473
+ admitted. A world without one sends no form.
474
+
475
+ The `scripting.ui` family of the parity suite records each rule below on the pinned BDS, and its
476
+ scenarios compare the form JSON a client receives byte for byte.
477
+
478
+ - **The JSON.** `src/host/formJson.ts` writes what BDS's JSON writer writes: keys in byte order,
479
+ a newline at the end, only `"`, `\` and control characters escaped, and a slider's 32-bit
480
+ float bounds in BDS's float format, so 0.5 is `0.50` and 0.1 is `0.1000000014901161`. A
481
+ `RawMessage` becomes a `rawtext` list, and one that holds nothing throws BDS's
482
+ `RawMessageError`. A builder call turns its arguments into JSON at once, so a script that
483
+ changes a `RawMessage` afterwards does not change the form.
484
+ - **Where the state lives.** A form's parts and a response's data live beside the objects in the
485
+ pack's realm, in a `WeakMap` the host reaches through `src/host/formKit.ts`, so a form a script
486
+ drops goes with it. Reading an argument runs inside the engine, under the watchdog.
487
+ - **The answer.** `show()` returns a promise, and the client's answer settles it in the next
488
+ script flush, before its promise jobs run. A cancel reason wins over JSON: 1 is `UserBusy` and
489
+ any other byte `UserClosed`. An action form takes an integer, read as a 32-bit unsigned
490
+ number, or a boolean; a modal form takes a flat list, with `null` read as `undefined` in
491
+ version 2 only; a message form reads `true` as its first button in version 2 and as its
492
+ second in version 1, whose JSON swaps the two buttons. Anything else rejects with
493
+ `FormRejectError` and `MalformedResponse`. An answer for a form the player was not sent, or
494
+ with neither JSON nor a reason, is dropped.
495
+ - **Leaving.** A player who leaves rejects each of their open forms with `PlayerQuit`, the
496
+ newest first. `show()` for that player then throws `InvalidEntityError`, and `closeAllForms`
497
+ throws `Error: Invalid Player handle.`. `closeAllForms` closes a player's forms and settles
498
+ none of them.
499
+
500
+ ### GameTests
501
+
502
+ A pack that declares `@minecraft/server-gametest` gets `register`, `registerAsync`,
503
+ `RegistrationBuilder`, a running test's `Test`, `spawnSimulatedPlayer` and `SimulatedPlayer`.
504
+ `WorldScripts.gametest` takes BDS's `/gametest` subcommands: `run <name>`, `runset [tag]`,
505
+ `stopall` and `clearall`. BDS has no `runall`; `runset` with no tag runs `suite:default`, which
506
+ a test is in only when it says so, and a tag also matches every test of the class it names.
507
+
508
+ The `gametest` scenario of the parity suite's `scripting.gametest` family records the runner on
509
+ the pinned BDS, and `src/host/gametest.ts` follows it:
510
+
511
+ - **Batches.** The tests that name a batch run first, a batch per name, then the rest as one
512
+ batch. Each batch starts in a script flush, and the next one four ticks after the last test of
513
+ the one before ends.
514
+ - **A test.** Starting a batch places each test's structure through
515
+ `ScriptWorld.placeStructure` and calls each test function in registration order. A test whose
516
+ `structures/<namespace>/<name>.mcstructure` no pack has fails without running.
517
+ - **Ticks.** In each later flush, before any system task, a running test's due `runAfterDelay`
518
+ callbacks and `idle` promises run, then its `succeedWhen` callbacks, the first of which also
519
+ runs when `succeedWhen` is called. A `succeedWhen` callback that returns without throwing passes
520
+ the test.
521
+ - **The end.** `succeed` and `fail` end a test at once, an uncaught error fails it, and a test
522
+ still running `maxTicks` ticks after it started fails with BDS's `Didn't succeed or fail within`
523
+ message. A failed `assert` throws `GameTestError`, which a script may catch. Once a test has
524
+ ended, every `Test` member but `isCompleted` throws `GameTestCompletedError`.
525
+ - **Cleanup.** The next flush takes an ended test's simulated players out of the world, and its
526
+ `Test` object stops working. A test that runs out of ticks is cleaned up as it fails.
527
+
528
+ A simulated player is a player of the world with no client, which the world adds through
529
+ `ScriptWorld.simulatedPlayers`. Every `Player` and `Entity` member works on it, and a pack that
530
+ declares the module gets a `SimulatedPlayer` object for it. Its `chat`, moves, jumps, looks,
531
+ attacks and item uses reach the world as `SimulatedPlayerAction`s, and `simulatedPlayers.tick`
532
+ moves it once per flush.
533
+
534
+ ### Custom commands and components
535
+
536
+ A version 2 pack registers custom commands, command enums and custom components in
537
+ `system.beforeEvents.startup`, through the event's `customCommandRegistry`,
538
+ `blockComponentRegistry` and `itemComponentRegistry`. A version 1 pack registers components in
539
+ `world.beforeEvents.worldInitialize`. `src/host/customContent.ts` checks each registration as BDS
540
+ does, and the `custom-commands` and `custom-components` scenarios of the parity suite record BDS's
541
+ errors: a name needs a namespace other than `minecraft`, a name registers once, an `Enum`
542
+ parameter needs its enum registered first, and a registration outside `startup` throws
543
+ `CustomCommandError` or `CustomComponentInvalidRegistryError`. A component's hooks are read when it
544
+ registers, and a hook that is not a function throws BDS's conversion error.
545
+
546
+ - **Commands.** After `startup` the runtime hands the world its commands through
547
+ `ScriptWorld.registerCommands`, with their parameters, permission levels, `cheatsRequired` and
548
+ enums, and logs and leaves out a command whose name has an upper-case letter, as BDS does. The
549
+ world parses a command's arguments and calls the set's `run`, which runs the callback in
550
+ restricted execution with a `CustomCommandOrigin` and the arguments, and answers its
551
+ `CustomCommandResult`. A callback that throws fails the command with the error's message, after
552
+ the content log has it. A reload takes the commands out and registers the new ones.
553
+ - **Components.** Once every lifecycle has had its chance to register, the runtime binds a
554
+ `ScriptComponentSink` through `ScriptWorld.bindComponents`. The world names, for each hook, the
555
+ components the block or item names, each with the parameters its pack JSON gives it, and the
556
+ sink runs the hook of every registered component that has it, in that order, with an event of
557
+ the class the pack's own `@minecraft/server` version gives the hook and a
558
+ `CustomComponentParameters`. `beforeOnPlayerPlace` runs at once, in restricted execution, and its
559
+ `cancel` refuses the placement. Every other hook waits for the script flush, where BDS ran it.
560
+ A block that names a component in `minecraft:custom_components` gets no parameters and no
561
+ `onBreak`, as on BDS.
562
+
563
+ ### HTTP requests and server configuration
564
+
565
+ `@minecraft/server-net` and `@minecraft/server-admin` are beta modules, so a pack that declares
566
+ either needs the Beta APIs experiment and a `permissions.json` that allows the module: BDS's
567
+ shipped `config/default/permissions.json` lists `@minecraft/server-admin` and leaves
568
+ `@minecraft/server-net` out. The `scripting.net` and `scripting.admin` families of the parity suite
569
+ record each rule below on the pinned BDS.
570
+
571
+ - **Requests.** `HttpRequest` and `HttpHeader` keep what a script sets. A request's `headers` is
572
+ one list per request, filled again with new `HttpHeader`s on each read, so a list read earlier
573
+ grows with `addHeader`. `http.get` and `http.request` hand the request to the world's
574
+ `ScriptHttpChannel` (`ScriptWorld.http`) and return a promise. A URI whose scheme is not `http`
575
+ or `https` rejects with `MalformedUriError` and reaches no network, and `cancelAll` rejects every
576
+ request the pack has in flight with a plain `Error` of its reason.
577
+ - **Responses are inputs.** The network runs off the tick. Its result enters the world through the
578
+ input step, which records it, and settles the request in the next script flush, before its
579
+ promise jobs run ([ADR 0021](../../docs/adr/0021-the-script-watchdog-counts-steps.md)). A replay
580
+ admits the recorded results in the same ticks, so it settles the same promises the same way
581
+ without the network. A failure rejects with `InternalHttpRequestError` and the code BDS's HTTP
582
+ client gives it, such as 111 for a refused connection or `E_FAIL` for a timeout.
583
+ - **Variables and secrets.** `variables` and `secrets` read the pack's `variables.json` and
584
+ `secrets.json`. `variables.get` returns a copy, its object keys in byte order. `secrets.get`
585
+ returns a new `SecretString` each time, which a script cannot read; only a request header sends
586
+ its text. A secret that is not a string is dropped with BDS's warning.
587
+ - **Transfers.** `transferPlayer` takes a player and either a hostname with a port or a NetherNet
588
+ id, and hands it to `ScriptWorld.transferPlayer`.
589
+
590
+ ### Debug shapes
591
+
592
+ `@minecraft/debug-utilities` is a beta module that BDS's shipped `permissions.json` allows. Its
593
+ shapes and `debugDrawer` have behavior; the `scripting.debug` family of the parity suite records
594
+ each rule below on the pinned BDS.
595
+
596
+ - **Shapes keep what a script sets.** Each class starts with BDS's defaults. A float property keeps
597
+ what a 32-bit float keeps, so `scale = 1.1` reads back `1.100000023841858`, and an integer
598
+ property drops its fraction. A `DimensionLocation` sets the shape's `dimension`, and a
599
+ `RawMessage` text reads back inside `rawtext`.
600
+ - **The drawer.** `addShape`, `removeShape`, `removeAll` and a shape's `remove` decide which shapes
601
+ the pack draws. At the end of each script flush the drawer hands `ScriptWorld.drawDebugShapes`
602
+ the shapes that are new or changed and the ones that went, so a world sends a shape again only
603
+ when the script changed it. A dimension given to `addShape` draws the shape there without
604
+ becoming its `dimension`, as on BDS. A reload removes every shape the old runtime drew.
605
+ - **Time left counts in ticks.** The drawer's step takes 0.05 seconds off each drawn shape's
606
+ `timeLeft`, and drops the shape once it reaches 0. A shape taken out loses that tick's time too.
607
+ BDS takes off the frame's elapsed time instead, which depends on its load, so the scenario
608
+ records which way each count moves rather than its values.
609
+ - **Not implemented.** `collectRuntimeStats` and `collectPluginStats` would read the engine's
610
+ memory, which differs from BDS's and from one build to the next, and the diagnostics classes
611
+ send stats to a client JSPrismarine does not have. They throw `NotImplementedError`.
612
+ `disableWatchdogTimingWarnings` does nothing, as the watchdog counts steps and never warns about
613
+ time.
614
+
615
+ `@minecraft/diagnostics` and `@minecraft/server-graphics` are served with no behavior, and BDS's
616
+ shipped `permissions.json` allows neither.
617
+
618
+ ## Building it
619
+
620
+ In a checkout, `pnpm install` runs the install script too, and downloads the published build while
621
+ the native sources match the manifest. After a change to them, build the library for this machine:
622
+
623
+ ```bash
624
+ pnpm --filter @jsprismarine/script-host run build:native
625
+ ```
626
+
627
+ The build needs a C compiler, `tar` that reads `.tar.xz`, and `git`. The compiler is `cc` on Linux
628
+ and macOS and MinGW-w64's `gcc` on Windows, unless `CC` names another. Bellard's QuickJS includes
629
+ `<sys/time.h>` and uses pthreads, so MSVC cannot build it. The script downloads the QuickJS release
630
+ that `native/sources.json` pins into `node_modules/.cache/jsprismarine/script-host`, checks its
631
+ SHA-256, applies the patches in `native/patches/`, and compiles QuickJS with `native/src/engine.c`
632
+ into one shared library that exports only the `jsh_` interface. It writes the library to
633
+ `prebuilds/<platform>/` with a `build.json` that records its digest, and the binding accepts that
634
+ digest as well as the published one.
635
+
636
+ The native sources' hash, from `src/nativeHash.ts`, names a set of builds. The Script host workflow
637
+ builds every platform in CI, on Debian 12 for a glibc floor of 2.36 and on Alpine for musl, loads
638
+ each build, fails one that needs a library a bare machine lacks, runs this package's tests against
639
+ the builds, and installs the packed package from an npm project. When a push to `master` changes
640
+ the native sources, it attaches the builds to a GitHub release named for the hash and opens a pull
641
+ request that points the manifest at them. Until that merges, every CI job that installs the
642
+ repository builds its own library, or restores the one built for the same sources from the cache.
643
+
644
+ ## The QuickJS patch
645
+
646
+ The patch adds these functions to QuickJS. Nothing in QuickJS behaves differently until the C layer
647
+ calls one:
648
+
649
+ - `JS_DisableFunctionFromString`, which makes the four `Function` constructors throw instead of
650
+ compiling a string.
651
+ - `JS_GetStackOverflowCount`, which counts the stack overflows a runtime throws, caught or not.
652
+ - `JS_ResetInterruptCounter`, which restarts the count of polls until the next interrupt handler
653
+ call, so each call from the host counts its steps from zero.
654
+ - `JS_DisableNewRegExpSyntax`, which makes the regular expression compiler refuse the `v` flag,
655
+ modifier groups and a group name used twice, as releases before them did.
656
+ - `JS_AddLegacyMembers`, which defines `Object.__getClass` and `String.prototype.__quote` as
657
+ earlier releases defined them.
658
+ - `JS_ExecutePendingJobOf`, which runs the first pending promise job of one context and leaves the
659
+ jobs of the others queued.
660
+
661
+ `native/patches/quickjs-debugger.patch` ports the debugger hooks of koush's QuickJS fork
662
+ (`koush/quickjs`, `quickjs-debugger.c` and its `quickjs.c` changes), which the VS Code extension's
663
+ protocol was written against. As koush's does, the interpreter keeps a second dispatch table whose
664
+ entries call the debugger before each instruction. A function uses it only when a line hook is
665
+ set as it starts, so with no debugger attached every instruction runs the usual table and does
666
+ no extra work. The patch adds:
667
+
668
+ - `JS_SetDebugHooks`, which sets a line hook and a throw hook. The line hook runs before the first
669
+ instruction of each line, when a loop jumps back, and when a call returns to a line partway
670
+ through. The throw hook runs once for each thrown value, before any handler.
671
+ - `JS_GetDebugStackDepth` and `JS_GetDebugFrame`, the stack with each frame's function, file,
672
+ line and column.
673
+ - `JS_GetDebugLocals` and `JS_GetDebugClosure`, a frame's variables.
674
+ - `JS_DebugEvaluate`, which compiles source as a direct `eval` inside a frame with all of the
675
+ frame's variables in scope. A variable no closure captures has no reference in its frame, so
676
+ the evaluation borrows the variable's slot and leaves any closure it made with a copy.
677
+ - `JS_GetDebugClassName`, an object's class name without running script.
678
+
679
+ `native/patches/quickjs-backtrace-oom.patch` fixes a use-after-free in QuickJS. When a script
680
+ runs out of memory, the interpreter adds the stack to the error it throws, and the string for the
681
+ stack can be the allocation that fails. That failure throws a new error, which frees the one the
682
+ stack was for, and the stack was then written to freed memory. The patch keeps a reference to the
683
+ error until its stack is set, and leaves the stack `null` when its string cannot be made. The
684
+ memory limit is hit at a different allocation on each C library, and Windows's was this one.