@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.
- package/CHANGELOG.md +99 -0
- package/LICENSE +21 -0
- package/README.md +667 -28
- package/dist/ScriptEngine.d.ts +250 -0
- package/dist/ScriptEngine.d.ts.map +1 -0
- package/dist/ScriptEngine.js +427 -0
- package/dist/ScriptEngine.js.map +1 -0
- package/dist/absentGlobals.d.ts +29 -0
- package/dist/absentGlobals.d.ts.map +1 -0
- package/dist/absentGlobals.js +94 -0
- package/dist/absentGlobals.js.map +1 -0
- package/dist/debugger/DebugSession.d.ts +189 -0
- package/dist/debugger/DebugSession.d.ts.map +1 -0
- package/dist/debugger/DebugSession.js +588 -0
- package/dist/debugger/DebugSession.js.map +1 -0
- package/dist/debugger/EngineDebugger.d.ts +158 -0
- package/dist/debugger/EngineDebugger.d.ts.map +1 -0
- package/dist/debugger/EngineDebugger.js +174 -0
- package/dist/debugger/EngineDebugger.js.map +1 -0
- package/dist/debugger/channel.d.ts +67 -0
- package/dist/debugger/channel.d.ts.map +1 -0
- package/dist/debugger/channel.js +120 -0
- package/dist/debugger/channel.js.map +1 -0
- package/dist/debugger/connectionWorker.d.ts +2 -0
- package/dist/debugger/connectionWorker.d.ts.map +1 -0
- package/dist/debugger/connectionWorker.js +98 -0
- package/dist/debugger/connectionWorker.js.map +1 -0
- package/dist/debugger/framing.d.ts +46 -0
- package/dist/debugger/framing.d.ts.map +1 -0
- package/dist/debugger/framing.js +106 -0
- package/dist/debugger/framing.js.map +1 -0
- package/dist/debugger/profiler.d.ts +72 -0
- package/dist/debugger/profiler.d.ts.map +1 -0
- package/dist/debugger/profiler.js +92 -0
- package/dist/debugger/profiler.js.map +1 -0
- package/dist/debugger/protocol.d.ts +170 -0
- package/dist/debugger/protocol.d.ts.map +1 -0
- package/dist/debugger/protocol.js +141 -0
- package/dist/debugger/protocol.js.map +1 -0
- package/dist/debugger/thread.d.ts +85 -0
- package/dist/debugger/thread.d.ts.map +1 -0
- package/dist/debugger/thread.js +134 -0
- package/dist/debugger/thread.js.map +1 -0
- package/dist/debugger/transport.d.ts +80 -0
- package/dist/debugger/transport.d.ts.map +1 -0
- package/dist/debugger/transport.js +150 -0
- package/dist/debugger/transport.js.map +1 -0
- package/dist/engineSource.d.ts +14 -0
- package/dist/engineSource.d.ts.map +1 -0
- package/dist/engineSource.js +17 -0
- package/dist/engineSource.js.map +1 -0
- package/dist/errors.d.ts +62 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +62 -0
- package/dist/errors.js.map +1 -0
- package/dist/ffi.d.ts +63 -0
- package/dist/ffi.d.ts.map +1 -0
- package/dist/ffi.js +156 -0
- package/dist/ffi.js.map +1 -0
- package/dist/generated/script-modules/common.d.ts +2 -0
- package/dist/generated/script-modules/common.js +262 -0
- package/dist/generated/script-modules/common.js.map +1 -0
- package/dist/generated/script-modules/common.json.d.ts +2 -0
- package/dist/generated/script-modules/debug-utilities.d.ts +2 -0
- package/dist/generated/script-modules/debug-utilities.js +23 -0
- package/dist/generated/script-modules/debug-utilities.js.map +1 -0
- package/dist/generated/script-modules/debug-utilities.json.d.ts +2 -0
- package/dist/generated/script-modules/diagnostics.d.ts +2 -0
- package/dist/generated/script-modules/diagnostics.js +281 -0
- package/dist/generated/script-modules/diagnostics.js.map +1 -0
- package/dist/generated/script-modules/diagnostics.json.d.ts +2 -0
- package/dist/generated/script-modules/server-admin.d.ts +2 -0
- package/dist/generated/script-modules/server-admin.js +23 -0
- package/dist/generated/script-modules/server-admin.js.map +1 -0
- package/dist/generated/script-modules/server-admin.json.d.ts +2 -0
- package/dist/generated/script-modules/server-gametest.d.ts +2 -0
- package/dist/generated/script-modules/server-gametest.js +23 -0
- package/dist/generated/script-modules/server-gametest.js.map +1 -0
- package/dist/generated/script-modules/server-gametest.json.d.ts +2 -0
- package/dist/generated/script-modules/server-graphics.d.ts +2 -0
- package/dist/generated/script-modules/server-graphics.js +30 -0
- package/dist/generated/script-modules/server-graphics.js.map +1 -0
- package/dist/generated/script-modules/server-graphics.json.d.ts +2 -0
- package/dist/generated/script-modules/server-net.d.ts +2 -0
- package/dist/generated/script-modules/server-net.js +24 -0
- package/dist/generated/script-modules/server-net.js.map +1 -0
- package/dist/generated/script-modules/server-net.json.d.ts +2 -0
- package/dist/generated/script-modules/server-ui.d.ts +2 -0
- package/dist/generated/script-modules/server-ui.js +110 -0
- package/dist/generated/script-modules/server-ui.js.map +1 -0
- package/dist/generated/script-modules/server-ui.json.d.ts +2 -0
- package/dist/generated/script-modules/server.d.ts +2 -0
- package/dist/generated/script-modules/server.js +251 -0
- package/dist/generated/script-modules/server.js.map +1 -0
- package/dist/generated/script-modules/server.json.d.ts +2 -0
- package/dist/generated/scriptApi.d.ts +3233 -0
- package/dist/generated/scriptApi.d.ts.map +1 -0
- package/dist/generated/scriptApi.js +0 -0
- package/dist/generated/scriptModules.d.ts +13 -0
- package/dist/generated/scriptModules.d.ts.map +1 -0
- package/dist/generated/scriptModules.js +34 -0
- package/dist/generated/scriptModules.js.map +1 -0
- package/dist/host/PackForms.d.ts +71 -0
- package/dist/host/PackForms.d.ts.map +1 -0
- package/dist/host/PackForms.js +164 -0
- package/dist/host/PackForms.js.map +1 -0
- package/dist/host/ScriptForms.d.ts +51 -0
- package/dist/host/ScriptForms.d.ts.map +1 -0
- package/dist/host/ScriptForms.js +103 -0
- package/dist/host/ScriptForms.js.map +1 -0
- package/dist/host/ScriptHttp.d.ts +54 -0
- package/dist/host/ScriptHttp.d.ts.map +1 -0
- package/dist/host/ScriptHttp.js +82 -0
- package/dist/host/ScriptHttp.js.map +1 -0
- package/dist/host/WorldScripts.d.ts +350 -0
- package/dist/host/WorldScripts.d.ts.map +1 -0
- package/dist/host/WorldScripts.js +1421 -0
- package/dist/host/WorldScripts.js.map +1 -0
- package/dist/host/blocksItems/blockComponents.d.ts +27 -0
- package/dist/host/blocksItems/blockComponents.d.ts.map +1 -0
- package/dist/host/blocksItems/blockComponents.js +73 -0
- package/dist/host/blocksItems/blockComponents.js.map +1 -0
- package/dist/host/blocksItems/blocks.d.ts +12 -0
- package/dist/host/blocksItems/blocks.d.ts.map +1 -0
- package/dist/host/blocksItems/blocks.js +247 -0
- package/dist/host/blocksItems/blocks.js.map +1 -0
- package/dist/host/blocksItems/componentFacts.d.ts +14 -0
- package/dist/host/blocksItems/componentFacts.d.ts.map +1 -0
- package/dist/host/blocksItems/componentFacts.js +34 -0
- package/dist/host/blocksItems/componentFacts.js.map +1 -0
- package/dist/host/blocksItems/containers.d.ts +18 -0
- package/dist/host/blocksItems/containers.d.ts.map +1 -0
- package/dist/host/blocksItems/containers.js +128 -0
- package/dist/host/blocksItems/containers.js.map +1 -0
- package/dist/host/blocksItems/handles.d.ts +10 -0
- package/dist/host/blocksItems/handles.d.ts.map +1 -0
- package/dist/host/blocksItems/handles.js +30 -0
- package/dist/host/blocksItems/handles.js.map +1 -0
- package/dist/host/blocksItems/implement.d.ts +22 -0
- package/dist/host/blocksItems/implement.d.ts.map +1 -0
- package/dist/host/blocksItems/implement.js +23 -0
- package/dist/host/blocksItems/implement.js.map +1 -0
- package/dist/host/blocksItems/itemExtras.d.ts +8 -0
- package/dist/host/blocksItems/itemExtras.d.ts.map +1 -0
- package/dist/host/blocksItems/itemExtras.js +106 -0
- package/dist/host/blocksItems/itemExtras.js.map +1 -0
- package/dist/host/blocksItems/itemLink.d.ts +12 -0
- package/dist/host/blocksItems/itemLink.d.ts.map +1 -0
- package/dist/host/blocksItems/itemLink.js +38 -0
- package/dist/host/blocksItems/itemLink.js.map +1 -0
- package/dist/host/blocksItems/items.d.ts +25 -0
- package/dist/host/blocksItems/items.d.ts.map +1 -0
- package/dist/host/blocksItems/items.js +427 -0
- package/dist/host/blocksItems/items.js.map +1 -0
- package/dist/host/blocksItems/tags.d.ts +24 -0
- package/dist/host/blocksItems/tags.d.ts.map +1 -0
- package/dist/host/blocksItems/tags.js +27 -0
- package/dist/host/blocksItems/tags.js.map +1 -0
- package/dist/host/blocksItems/types.d.ts +13 -0
- package/dist/host/blocksItems/types.d.ts.map +1 -0
- package/dist/host/blocksItems/types.js +83 -0
- package/dist/host/blocksItems/types.js.map +1 -0
- package/dist/host/blocksItems/volumes.d.ts +37 -0
- package/dist/host/blocksItems/volumes.d.ts.map +1 -0
- package/dist/host/blocksItems/volumes.js +361 -0
- package/dist/host/blocksItems/volumes.js.map +1 -0
- package/dist/host/coverage.d.ts +28 -0
- package/dist/host/coverage.d.ts.map +1 -0
- package/dist/host/coverage.js +45 -0
- package/dist/host/coverage.js.map +1 -0
- package/dist/host/customContent.d.ts +81 -0
- package/dist/host/customContent.d.ts.map +1 -0
- package/dist/host/customContent.js +213 -0
- package/dist/host/customContent.js.map +1 -0
- package/dist/host/debugUtilities.d.ts +192 -0
- package/dist/host/debugUtilities.d.ts.map +1 -0
- package/dist/host/debugUtilities.js +503 -0
- package/dist/host/debugUtilities.js.map +1 -0
- package/dist/host/entities/aimAssist.d.ts +11 -0
- package/dist/host/entities/aimAssist.d.ts.map +1 -0
- package/dist/host/entities/aimAssist.js +195 -0
- package/dist/host/entities/aimAssist.js.map +1 -0
- package/dist/host/entities/area.d.ts +14 -0
- package/dist/host/entities/area.d.ts.map +1 -0
- package/dist/host/entities/area.js +19 -0
- package/dist/host/entities/area.js.map +1 -0
- package/dist/host/entities/components.d.ts +61 -0
- package/dist/host/entities/components.d.ts.map +1 -0
- package/dist/host/entities/components.js +642 -0
- package/dist/host/entities/components.js.map +1 -0
- package/dist/host/entities/entityMembers.d.ts +35 -0
- package/dist/host/entities/entityMembers.d.ts.map +1 -0
- package/dist/host/entities/entityMembers.js +494 -0
- package/dist/host/entities/entityMembers.js.map +1 -0
- package/dist/host/entities/playerMembers.d.ts +23 -0
- package/dist/host/entities/playerMembers.d.ts.map +1 -0
- package/dist/host/entities/playerMembers.js +576 -0
- package/dist/host/entities/playerMembers.js.map +1 -0
- package/dist/host/entities/world.d.ts +315 -0
- package/dist/host/entities/world.d.ts.map +1 -0
- package/dist/host/entities/world.js +0 -0
- package/dist/host/events/componentEvents.d.ts +11 -0
- package/dist/host/events/componentEvents.d.ts.map +1 -0
- package/dist/host/events/componentEvents.js +23 -0
- package/dist/host/events/componentEvents.js.map +1 -0
- package/dist/host/events/eventOptions.d.ts +14 -0
- package/dist/host/events/eventOptions.d.ts.map +1 -0
- package/dist/host/events/eventOptions.js +224 -0
- package/dist/host/events/eventOptions.js.map +1 -0
- package/dist/host/events/eventValues.d.ts +41 -0
- package/dist/host/events/eventValues.d.ts.map +1 -0
- package/dist/host/events/eventValues.js +89 -0
- package/dist/host/events/eventValues.js.map +1 -0
- package/dist/host/events/worldEvents.d.ts +30 -0
- package/dist/host/events/worldEvents.d.ts.map +1 -0
- package/dist/host/events/worldEvents.js +207 -0
- package/dist/host/events/worldEvents.js.map +1 -0
- package/dist/host/formJson.d.ts +35 -0
- package/dist/host/formJson.d.ts.map +1 -0
- package/dist/host/formJson.js +84 -0
- package/dist/host/formJson.js.map +1 -0
- package/dist/host/formKit.d.ts +40 -0
- package/dist/host/formKit.d.ts.map +1 -0
- package/dist/host/formKit.js +124 -0
- package/dist/host/formKit.js.map +1 -0
- package/dist/host/forms.d.ts +92 -0
- package/dist/host/forms.d.ts.map +1 -0
- package/dist/host/forms.js +361 -0
- package/dist/host/forms.js.map +1 -0
- package/dist/host/gametest.d.ts +202 -0
- package/dist/host/gametest.d.ts.map +1 -0
- package/dist/host/gametest.js +316 -0
- package/dist/host/gametest.js.map +1 -0
- package/dist/host/inputs.d.ts +29 -0
- package/dist/host/inputs.d.ts.map +1 -0
- package/dist/host/inputs.js +110 -0
- package/dist/host/inputs.js.map +1 -0
- package/dist/host/jobs.d.ts +48 -0
- package/dist/host/jobs.d.ts.map +1 -0
- package/dist/host/jobs.js +62 -0
- package/dist/host/jobs.js.map +1 -0
- package/dist/host/jsprismarineServer.d.ts +65 -0
- package/dist/host/jsprismarineServer.d.ts.map +1 -0
- package/dist/host/jsprismarineServer.js +83 -0
- package/dist/host/jsprismarineServer.js.map +1 -0
- package/dist/host/minecraftServer.d.ts +229 -0
- package/dist/host/minecraftServer.d.ts.map +1 -0
- package/dist/host/minecraftServer.js +304 -0
- package/dist/host/minecraftServer.js.map +1 -0
- package/dist/host/minecraftServerUi.d.ts +30 -0
- package/dist/host/minecraftServerUi.d.ts.map +1 -0
- package/dist/host/minecraftServerUi.js +89 -0
- package/dist/host/minecraftServerUi.js.map +1 -0
- package/dist/host/netKit.d.ts +44 -0
- package/dist/host/netKit.d.ts.map +1 -0
- package/dist/host/netKit.js +87 -0
- package/dist/host/netKit.js.map +1 -0
- package/dist/host/pack.d.ts +71 -0
- package/dist/host/pack.d.ts.map +1 -0
- package/dist/host/pack.js +157 -0
- package/dist/host/pack.js.map +1 -0
- package/dist/host/serverAdmin.d.ts +44 -0
- package/dist/host/serverAdmin.d.ts.map +1 -0
- package/dist/host/serverAdmin.js +96 -0
- package/dist/host/serverAdmin.js.map +1 -0
- package/dist/host/serverBlocks.d.ts +32 -0
- package/dist/host/serverBlocks.d.ts.map +1 -0
- package/dist/host/serverBlocks.js +93 -0
- package/dist/host/serverBlocks.js.map +1 -0
- package/dist/host/serverComponents.d.ts +46 -0
- package/dist/host/serverComponents.d.ts.map +1 -0
- package/dist/host/serverComponents.js +297 -0
- package/dist/host/serverComponents.js.map +1 -0
- package/dist/host/serverCustom.d.ts +16 -0
- package/dist/host/serverCustom.d.ts.map +1 -0
- package/dist/host/serverCustom.js +161 -0
- package/dist/host/serverCustom.js.map +1 -0
- package/dist/host/serverEntities.d.ts +49 -0
- package/dist/host/serverEntities.d.ts.map +1 -0
- package/dist/host/serverEntities.js +358 -0
- package/dist/host/serverEntities.js.map +1 -0
- package/dist/host/serverFeedback.d.ts +15 -0
- package/dist/host/serverFeedback.d.ts.map +1 -0
- package/dist/host/serverFeedback.js +413 -0
- package/dist/host/serverFeedback.js.map +1 -0
- package/dist/host/serverGametest.d.ts +43 -0
- package/dist/host/serverGametest.d.ts.map +1 -0
- package/dist/host/serverGametest.js +246 -0
- package/dist/host/serverGametest.js.map +1 -0
- package/dist/host/serverItems.d.ts +17 -0
- package/dist/host/serverItems.d.ts.map +1 -0
- package/dist/host/serverItems.js +71 -0
- package/dist/host/serverItems.js.map +1 -0
- package/dist/host/serverNet.d.ts +41 -0
- package/dist/host/serverNet.d.ts.map +1 -0
- package/dist/host/serverNet.js +289 -0
- package/dist/host/serverNet.js.map +1 -0
- package/dist/host/serverObjects.d.ts +142 -0
- package/dist/host/serverObjects.d.ts.map +1 -0
- package/dist/host/serverObjects.js +326 -0
- package/dist/host/serverObjects.js.map +1 -0
- package/dist/host/serverProperties.d.ts +48 -0
- package/dist/host/serverProperties.d.ts.map +1 -0
- package/dist/host/serverProperties.js +193 -0
- package/dist/host/serverProperties.js.map +1 -0
- package/dist/host/serverScoreboard.d.ts +9 -0
- package/dist/host/serverScoreboard.d.ts.map +1 -0
- package/dist/host/serverScoreboard.js +198 -0
- package/dist/host/serverScoreboard.js.map +1 -0
- package/dist/host/serverStructures.d.ts +9 -0
- package/dist/host/serverStructures.d.ts.map +1 -0
- package/dist/host/serverStructures.js +243 -0
- package/dist/host/serverStructures.js.map +1 -0
- package/dist/host/tasks.d.ts +66 -0
- package/dist/host/tasks.d.ts.map +1 -0
- package/dist/host/tasks.js +107 -0
- package/dist/host/tasks.js.map +1 -0
- package/dist/host/world.d.ts +1359 -0
- package/dist/host/world.d.ts.map +1 -0
- package/dist/host/world.js +10 -0
- package/dist/host/world.js.map +1 -0
- package/dist/host/worldsystem/gameRules.d.ts +189 -0
- package/dist/host/worldsystem/gameRules.d.ts.map +1 -0
- package/dist/host/worldsystem/gameRules.js +86 -0
- package/dist/host/worldsystem/gameRules.js.map +1 -0
- package/dist/host/worldsystem/memoryWorldSystem.d.ts +18 -0
- package/dist/host/worldsystem/memoryWorldSystem.d.ts.map +1 -0
- package/dist/host/worldsystem/memoryWorldSystem.js +223 -0
- package/dist/host/worldsystem/memoryWorldSystem.js.map +1 -0
- package/dist/host/worldsystem/seam.d.ts +163 -0
- package/dist/host/worldsystem/seam.d.ts.map +1 -0
- package/dist/host/worldsystem/seam.js +0 -0
- package/dist/host/worldsystem/serverClocks.d.ts +18 -0
- package/dist/host/worldsystem/serverClocks.d.ts.map +1 -0
- package/dist/host/worldsystem/serverClocks.js +166 -0
- package/dist/host/worldsystem/serverClocks.js.map +1 -0
- package/dist/host/worldsystem/serverDimension.d.ts +10 -0
- package/dist/host/worldsystem/serverDimension.d.ts.map +1 -0
- package/dist/host/worldsystem/serverDimension.js +388 -0
- package/dist/host/worldsystem/serverDimension.js.map +1 -0
- package/dist/host/worldsystem/serverFog.d.ts +15 -0
- package/dist/host/worldsystem/serverFog.d.ts.map +1 -0
- package/dist/host/worldsystem/serverFog.js +66 -0
- package/dist/host/worldsystem/serverFog.js.map +1 -0
- package/dist/host/worldsystem/serverLoot.d.ts +9 -0
- package/dist/host/worldsystem/serverLoot.d.ts.map +1 -0
- package/dist/host/worldsystem/serverLoot.js +255 -0
- package/dist/host/worldsystem/serverLoot.js.map +1 -0
- package/dist/host/worldsystem/serverPrimitiveShapes.d.ts +9 -0
- package/dist/host/worldsystem/serverPrimitiveShapes.d.ts.map +1 -0
- package/dist/host/worldsystem/serverPrimitiveShapes.js +149 -0
- package/dist/host/worldsystem/serverPrimitiveShapes.js.map +1 -0
- package/dist/host/worldsystem/serverTickingAreas.d.ts +11 -0
- package/dist/host/worldsystem/serverTickingAreas.d.ts.map +1 -0
- package/dist/host/worldsystem/serverTickingAreas.js +176 -0
- package/dist/host/worldsystem/serverTickingAreas.js.map +1 -0
- package/dist/host/worldsystem/serverVolumes.d.ts +9 -0
- package/dist/host/worldsystem/serverVolumes.d.ts.map +1 -0
- package/dist/host/worldsystem/serverVolumes.js +248 -0
- package/dist/host/worldsystem/serverVolumes.js.map +1 -0
- package/dist/host/worldsystem/serverWorld.d.ts +18 -0
- package/dist/host/worldsystem/serverWorld.d.ts.map +1 -0
- package/dist/host/worldsystem/serverWorld.js +199 -0
- package/dist/host/worldsystem/serverWorld.js.map +1 -0
- package/dist/host/worldsystem/tags.d.ts +40 -0
- package/dist/host/worldsystem/tags.d.ts.map +1 -0
- package/dist/host/worldsystem/tags.js +43 -0
- package/dist/host/worldsystem/tags.js.map +1 -0
- package/dist/install.d.ts +39 -0
- package/dist/install.d.ts.map +1 -0
- package/dist/install.js +83 -0
- package/dist/install.js.map +1 -0
- package/dist/isRecord.d.ts +3 -0
- package/dist/isRecord.d.ts.map +1 -0
- package/dist/isRecord.js +6 -0
- package/dist/isRecord.js.map +1 -0
- package/dist/library.d.ts +40 -0
- package/dist/library.d.ts.map +1 -0
- package/dist/library.js +101 -0
- package/dist/library.js.map +1 -0
- package/dist/manifest.d.ts +37 -0
- package/dist/manifest.d.ts.map +1 -0
- package/dist/manifest.js +40 -0
- package/dist/manifest.js.map +1 -0
- package/dist/native/manifest.json.js +45 -0
- package/dist/native/manifest.json.js.map +1 -0
- package/dist/nativeHash.d.ts +16 -0
- package/dist/nativeHash.d.ts.map +1 -0
- package/dist/nativeHash.js +52 -0
- package/dist/nativeHash.js.map +1 -0
- package/dist/platform.d.ts +50 -0
- package/dist/platform.d.ts.map +1 -0
- package/dist/platform.js +77 -0
- package/dist/platform.js.map +1 -0
- package/dist/shape/binding.d.ts +112 -0
- package/dist/shape/binding.d.ts.map +1 -0
- package/dist/shape/binding.js +558 -0
- package/dist/shape/binding.js.map +1 -0
- package/dist/shape/engineRuntime.d.ts +55 -0
- package/dist/shape/engineRuntime.d.ts.map +1 -0
- package/dist/shape/engineRuntime.js +451 -0
- package/dist/shape/engineRuntime.js.map +1 -0
- package/dist/shape/format.d.ts +249 -0
- package/dist/shape/format.d.ts.map +1 -0
- package/dist/shape/format.js +43 -0
- package/dist/shape/format.js.map +1 -0
- package/dist/shape/history.d.ts +24 -0
- package/dist/shape/history.d.ts.map +1 -0
- package/dist/shape/history.js +65 -0
- package/dist/shape/history.js.map +1 -0
- package/dist/shape/implementations.d.ts +105 -0
- package/dist/shape/implementations.d.ts.map +1 -0
- package/dist/shape/implementations.js +62 -0
- package/dist/shape/implementations.js.map +1 -0
- package/dist/shape/plan.d.ts +138 -0
- package/dist/shape/plan.d.ts.map +1 -0
- package/dist/shape/plan.js +0 -0
- package/dist/shape/resolve.d.ts +56 -0
- package/dist/shape/resolve.d.ts.map +1 -0
- package/dist/shape/resolve.js +78 -0
- package/dist/shape/resolve.js.map +1 -0
- package/dist/shape/version.d.ts +15 -0
- package/dist/shape/version.d.ts.map +1 -0
- package/dist/shape/version.js +35 -0
- package/dist/shape/version.js.map +1 -0
- package/dist/testing/debuggerWorker.d.ts +15 -0
- package/dist/testing/debuggerWorker.d.ts.map +1 -0
- package/dist/testing/debuggerWorker.js +29 -0
- package/dist/testing/debuggerWorker.js.map +1 -0
- package/dist/testing/engineWorker.d.ts +7 -0
- package/dist/testing/engineWorker.d.ts.map +1 -0
- package/dist/testing/engineWorker.js +31 -0
- package/dist/testing/engineWorker.js.map +1 -0
- package/dist/values.d.ts +94 -0
- package/dist/values.d.ts.map +1 -0
- package/dist/values.js +204 -0
- package/dist/values.js.map +1 -0
- package/native/manifest.json +49 -0
- package/package.json +177 -6
- package/scripts/postinstall.mjs +54 -0
package/README.md
CHANGED
|
@@ -1,45 +1,684 @@
|
|
|
1
1
|
# @jsprismarine/script-host
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://discord.gg/kZZCDyCBbW)
|
|
4
|
+
[](https://www.npmjs.com/package/@jsprismarine/script-host)
|
|
4
5
|
|
|
5
|
-
|
|
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
|
|
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
|
-
##
|
|
18
|
+
## Installing
|
|
10
19
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
3. Establish provenance for packages published under this name
|
|
20
|
+
```bash
|
|
21
|
+
npm install @jsprismarine/script-host
|
|
22
|
+
```
|
|
15
23
|
|
|
16
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
36
|
+
## Running a script
|
|
21
37
|
|
|
22
|
-
|
|
38
|
+
```ts
|
|
39
|
+
import { ScriptHostLibrary } from '@jsprismarine/script-host';
|
|
23
40
|
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
|
|
44
|
+
try {
|
|
45
|
+
engine.defineGlobalFunction('add', (a, b) => Number(a) + Number(b));
|
|
46
|
+
engine.evaluate('add(1, 2)'); // 3
|
|
30
47
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
48
|
+
engine.setBudget({ perCallback: 1000 });
|
|
49
|
+
engine.evaluate('while (true) {}'); // throws ScriptTerminatedError
|
|
50
|
+
} finally {
|
|
51
|
+
engine.destroy();
|
|
52
|
+
}
|
|
53
|
+
```
|
|
36
54
|
|
|
37
|
-
|
|
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
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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
|
-
|
|
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.
|