@wildshard/sdk 0.0.1 → 0.2.4
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/GUIDE.md +895 -0
- package/README.md +13 -5
- package/bin/wildshard.mjs +38 -0
- package/lint/declaration-config.d.mts +2 -0
- package/lint/declaration-config.mjs +19 -0
- package/lint/engine-plugin.d.mts +2 -0
- package/lint/engine-plugin.mjs +40 -0
- package/lint/host-callbacks.d.mts +6 -0
- package/lint/host-callbacks.mjs +123 -0
- package/lint/host-files.d.mts +1 -0
- package/lint/host-files.mjs +7 -0
- package/lint/layer-exports.d.mts +2 -0
- package/lint/layer-exports.mjs +21 -0
- package/lint/legacy-line-basis.json +995 -0
- package/lint/nine-tiling-baseline.json +35 -0
- package/lint/ratchet.json +11 -0
- package/lint/runtime-files.d.mts +12 -0
- package/lint/runtime-files.json +16 -0
- package/lint/runtime-files.mjs +69 -0
- package/lint/runtime-performance.d.mts +6 -0
- package/lint/runtime-performance.mjs +184 -0
- package/lint/sdk-plugin.d.mts +4 -0
- package/lint/sdk-plugin.mjs +134 -0
- package/lint/shardfile-boundaries.d.mts +10 -0
- package/lint/shardfile-boundaries.mjs +122 -0
- package/lint/tile-bake-debt.json +556 -0
- package/package.json +365 -3
- package/scripts/agent-parity.mjs +1524 -0
- package/scripts/agent-sync.mjs +518 -0
- package/scripts/apfs-clone.mjs +67 -0
- package/scripts/assert-store-layout.mjs +23 -0
- package/scripts/astc6-phone-cap.d.mts +3 -0
- package/scripts/astc6-phone-cap.mjs +137 -0
- package/scripts/audit-assets.d.mts +10 -0
- package/scripts/audit-assets.mjs +151 -0
- package/scripts/bake/coatFiles.d.mts +6 -0
- package/scripts/bake/coatFiles.mjs +37 -0
- package/scripts/bake/environment.d.mts +2 -0
- package/scripts/bake/environment.mjs +58 -0
- package/scripts/bake/far-proxies.mjs +45 -0
- package/scripts/bake/keyed-sky.d.mts +4 -0
- package/scripts/bake/keyed-sky.mjs +34 -0
- package/scripts/bake/movers.mjs +56 -0
- package/scripts/bake/nativeWorld.d.mts +6 -0
- package/scripts/bake/nativeWorld.mjs +43 -0
- package/scripts/bake/navmeshGround.ts +22 -0
- package/scripts/bake/near-placeholder.mjs +331 -0
- package/scripts/bake/placeholderShards.mjs +41 -0
- package/scripts/bake/skins.mjs +15 -0
- package/scripts/bake/template-skins.mjs +33 -0
- package/scripts/bake/viewmodelBytes.ts +26 -0
- package/scripts/bake/viewmodelPage.ts +11 -0
- package/scripts/bake/worldHost.d.mts +35 -0
- package/scripts/bake/worldHost.mjs +110 -0
- package/scripts/bake-astc6.cache.json +80 -0
- package/scripts/bake-astc6.far-reach.cache.json +23 -0
- package/scripts/bake-astc6.list.json +111 -0
- package/scripts/bake-astc6.mjs +279 -0
- package/scripts/bake-astc6.nalati-grasslands.cache.json +42 -0
- package/scripts/bake-catalogue.mjs +44 -0
- package/scripts/bake-check.mjs +54 -0
- package/scripts/bake-chunk.mjs +124 -0
- package/scripts/bake-cloud-field.mjs +24 -0
- package/scripts/bake-coats.mjs +110 -0
- package/scripts/bake-data-maps.d.mts +24 -0
- package/scripts/bake-data-maps.mjs +72 -0
- package/scripts/bake-entry-programs.mjs +117 -0
- package/scripts/bake-geometry.mjs +106 -0
- package/scripts/bake-hybrid-tiles.mjs +28 -0
- package/scripts/bake-ktx2.cache.json +276 -0
- package/scripts/bake-ktx2.list.json +365 -0
- package/scripts/bake-ktx2.mjs +477 -0
- package/scripts/bake-map-glb.mjs +127 -0
- package/scripts/bake-map-rest.d.mts +7 -0
- package/scripts/bake-map-rest.mjs +50 -0
- package/scripts/bake-maps.mjs +200 -0
- package/scripts/bake-navmesh.mjs +259 -0
- package/scripts/bake-packs.mjs +129 -0
- package/scripts/bake-pickups.mjs +102 -0
- package/scripts/bake-query-terrain.mjs +64 -0
- package/scripts/bake-recurve-pool.mjs +16 -0
- package/scripts/bake-section-schemas.d.mts +3 -0
- package/scripts/bake-template-shardfile.mjs +32 -0
- package/scripts/bake-textures.mjs +80 -0
- package/scripts/bake-viewmodel-sets.json +45 -0
- package/scripts/bake-viewmodel-sets.mjs +137 -0
- package/scripts/bake-voxel-ao.mjs +119 -0
- package/scripts/bake-water-ripples.mjs +25 -0
- package/scripts/blender/README.md +129 -0
- package/scripts/blender/build.sh +166 -0
- package/scripts/blender/lib/export-scene.mjs +129 -0
- package/scripts/blender/lib/glb-digest.mjs +188 -0
- package/scripts/blender/lib/glb.py +68 -0
- package/scripts/blender/lib/save_blend.py +17 -0
- package/scripts/blender/lib/world_fixture.py +55 -0
- package/scripts/blender/targets.json +591 -0
- package/scripts/build-sdk.mjs +95 -0
- package/scripts/build-shardfiles.d.mts +7 -0
- package/scripts/build-shardfiles.mjs +206 -0
- package/scripts/capture-hero.mjs +137 -0
- package/scripts/check-lift-review.mjs +23 -0
- package/scripts/chromium-keychain-check.mjs +139 -0
- package/scripts/chromium-keychain.d.mts +1 -0
- package/scripts/chromium-keychain.mjs +5 -0
- package/scripts/compile-script.d.mts +3 -0
- package/scripts/compile-script.mjs +8 -0
- package/scripts/creature-color.mjs +255 -0
- package/scripts/decide/calibrate.py +127 -0
- package/scripts/decide/calibration/2026-10-03/labels-s1.tsv +281 -0
- package/scripts/decide/calibration/2026-10-03/labels-s2.tsv +97 -0
- package/scripts/decide/calibration/2026-10-03/labels-s3.tsv +48 -0
- package/scripts/decide/calibration/2026-10-03/labels-s3b.tsv +26 -0
- package/scripts/decide/calibration/2026-10-03/res-capture-status-v1.jsonl +376 -0
- package/scripts/decide/calibration/2026-10-03/res-text-garbled-strings.jsonl +48 -0
- package/scripts/decide/calibration/2026-10-03/res-text-garbled-v1.jsonl +73 -0
- package/scripts/decide/decide.py +262 -0
- package/scripts/decide/decide.sh +50 -0
- package/scripts/decide/layer-purity-pilot.mjs +41 -0
- package/scripts/decide/sets/capture-status.json +46 -0
- package/scripts/decide/sets/layer-purity.json +28 -0
- package/scripts/decide/sets/text-garbled.json +17 -0
- package/scripts/decide/test_decide.py +37 -0
- package/scripts/docs.mjs +15 -0
- package/scripts/entry-reads/crawl.ts +152 -0
- package/scripts/entry-reads/tsconfig.json +25 -0
- package/scripts/gen-format-schema.d.mts +2 -0
- package/scripts/gen-format-schema.mjs +21 -0
- package/scripts/gen-host-catalogue.d.mts +14 -0
- package/scripts/gen-host-catalogue.mjs +108 -0
- package/scripts/gen-shard-layout-doc.d.mts +4 -0
- package/scripts/gen-shard-layout-doc.mjs +55 -0
- package/scripts/gen-shards.d.mts +17 -0
- package/scripts/gen-shards.mjs +311 -0
- package/scripts/goldens/capture-inputs.d.mts +4 -0
- package/scripts/goldens/capture-inputs.mjs +34 -0
- package/scripts/goldens/colour_shift.py +27 -0
- package/scripts/goldens/native-residency.d.mts +10 -0
- package/scripts/goldens/native-residency.mjs +104 -0
- package/scripts/goldens/plot-inputs.d.mts +12 -0
- package/scripts/goldens/plot-inputs.mjs +46 -0
- package/scripts/gpu-texmem.mjs +98 -0
- package/scripts/horizon-matte/config.py +24 -0
- package/scripts/horizon-matte/encode.py +91 -0
- package/scripts/horizon-matte/key.py +141 -0
- package/scripts/horizon-matte/mkjobs.py +33 -0
- package/scripts/horizon-matte/mkjobs_day2.py +11 -0
- package/scripts/horizon-matte/overlap.py +80 -0
- package/scripts/horizon-matte/run_codex.py +57 -0
- package/scripts/horizon-matte/stitch.py +133 -0
- package/scripts/img2mesh/CC0.md +105 -0
- package/scripts/img2mesh/README.md +209 -0
- package/scripts/img2mesh/ab_board.py +102 -0
- package/scripts/img2mesh/birds/birds.json +255 -0
- package/scripts/img2mesh/birds/birds_atlas.py +150 -0
- package/scripts/img2mesh/birds/birds_fix_preview.mjs +103 -0
- package/scripts/img2mesh/birds/birds_fix_render.py +75 -0
- package/scripts/img2mesh/birds/birds_pack.py +110 -0
- package/scripts/img2mesh/birds/birds_phone_b.py +112 -0
- package/scripts/img2mesh/birds/birds_post.py +550 -0
- package/scripts/img2mesh/birds/birds_render.py +125 -0
- package/scripts/img2mesh/birds/birds_sheet.py +33 -0
- package/scripts/img2mesh/birds/birds_view.py +60 -0
- package/scripts/img2mesh/board.py +100 -0
- package/scripts/img2mesh/build_cc0.sh +52 -0
- package/scripts/img2mesh/build_driftwood.sh +12 -0
- package/scripts/img2mesh/build_faces.sh +53 -0
- package/scripts/img2mesh/build_props.py +81 -0
- package/scripts/img2mesh/cc0_export.py +186 -0
- package/scripts/img2mesh/driftwood_post.py +571 -0
- package/scripts/img2mesh/e304_faces.sh +67 -0
- package/scripts/img2mesh/face_remaster.py +911 -0
- package/scripts/img2mesh/face_views.py +95 -0
- package/scripts/img2mesh/faces-e304.json +9 -0
- package/scripts/img2mesh/faces.json +30 -0
- package/scripts/img2mesh/head_cut.py +100 -0
- package/scripts/img2mesh/hi3d_paint.py +94 -0
- package/scripts/img2mesh/hi3d_refine.py +161 -0
- package/scripts/img2mesh/hunyuan_cpu_rasterizer.sh +42 -0
- package/scripts/img2mesh/pine_hollow_phone.sh +13 -0
- package/scripts/img2mesh/props/coral-arch.json +32 -0
- package/scripts/img2mesh/props/ember-furnace.json +30 -0
- package/scripts/img2mesh/props/night-market-gate.json +10 -0
- package/scripts/img2mesh/render_still.py +86 -0
- package/scripts/img2mesh/rig_strip.mjs +46 -0
- package/scripts/img2mesh/rig_transfer.mjs +104 -0
- package/scripts/img2mesh/split_sheet.py +48 -0
- package/scripts/img2mesh/trellis_batch.py +110 -0
- package/scripts/img2mesh/versus_board.py +114 -0
- package/scripts/import-bundle.d.mts +2 -0
- package/scripts/import-bundle.mjs +20 -0
- package/scripts/ktx2-ab-board.py +133 -0
- package/scripts/ktx2-ab.mjs +111 -0
- package/scripts/ktx2-settings.mjs +18 -0
- package/scripts/land.d.mts +14 -0
- package/scripts/land.mjs +809 -0
- package/scripts/lint-dispatch.mjs +14 -0
- package/scripts/map-bake-frames.d.mts +4 -0
- package/scripts/map-bake-frames.mjs +23 -0
- package/scripts/map-geometry.d.mts +9 -0
- package/scripts/map-geometry.mjs +29 -0
- package/scripts/map-world.mjs +162 -0
- package/scripts/mockup-local.sh +46 -0
- package/scripts/music/export-midi.mjs +68 -0
- package/scripts/music/gen/analyze.py +308 -0
- package/scripts/music/gen/audio_jobs.py +46 -0
- package/scripts/music/gen/briefs.json +51 -0
- package/scripts/music/gen/build_page.py +334 -0
- package/scripts/music/gen/folk.json +3187 -0
- package/scripts/music/gen/gen_ace_step.py +156 -0
- package/scripts/music/gen/gen_heartmula.py +187 -0
- package/scripts/music/gen/gen_minimax.py +143 -0
- package/scripts/music/gen/gen_sao.py +122 -0
- package/scripts/music/gen/gen_sao_small.py +104 -0
- package/scripts/music/gen/gen_sfx.py +98 -0
- package/scripts/music/gen/gen_sfx_ezaudio.py +112 -0
- package/scripts/music/gen/gen_sfx_moss.py +112 -0
- package/scripts/music/gen/models.json +61 -0
- package/scripts/music/gen/nalati-jobs.json +104 -0
- package/scripts/music/gen/nalati-score-build.json +119 -0
- package/scripts/music/gen/nalati-score.json +3448 -0
- package/scripts/music/gen/ob7-fit-decisions.json +38 -0
- package/scripts/music/gen/ob7-score-jobs.json +152 -0
- package/scripts/music/gen/ob7-sfx-jobs.json +897 -0
- package/scripts/music/gen/ob7_build.py +469 -0
- package/scripts/music/gen/ob7_generate.py +67 -0
- package/scripts/music/gen/ob7_run.sh +42 -0
- package/scripts/music/gen/orchestral.json +3187 -0
- package/scripts/music/gen/own_score.py +486 -0
- package/scripts/music/gen/ph-jobs.json +27 -0
- package/scripts/music/gen/ph_page.py +222 -0
- package/scripts/music/gen/piano.json +3175 -0
- package/scripts/music/gen/rank_v3.py +248 -0
- package/scripts/music/gen/sfx-best.json +2486 -0
- package/scripts/music/gen/sfx-ezaudio.json +4082 -0
- package/scripts/music/gen/sfx-jobs.json +57 -0
- package/scripts/music/gen/sfx-minimax-jobs.json +16 -0
- package/scripts/music/gen/sfx-minimax.json +289 -0
- package/scripts/music/gen/sfx-moss.json +4082 -0
- package/scripts/music/gen/sfx-nalati-b3-jobs.json +17 -0
- package/scripts/music/gen/sfx-nalati-jobs.json +338 -0
- package/scripts/music/gen/sfx-nalati.json +11202 -0
- package/scripts/music/gen/sfx-nd-jobs.json +57 -0
- package/scripts/music/gen/sfx-nd-moss.json +2097 -0
- package/scripts/music/gen/sfx-nd-sa3-medium.json +2097 -0
- package/scripts/music/gen/sfx-nd-summary.json +38 -0
- package/scripts/music/gen/sfx-peaks.json +7 -0
- package/scripts/music/gen/sfx-ph-jobs.json +169 -0
- package/scripts/music/gen/sfx-ph-moss.json +6564 -0
- package/scripts/music/gen/sfx-ph-sa3-medium.json +7239 -0
- package/scripts/music/gen/sfx-ph-summary.json +63 -0
- package/scripts/music/gen/sfx-sa3-medium.json +4082 -0
- package/scripts/music/gen/sfx-sa3.json +4082 -0
- package/scripts/music/gen/sfx-summary.json +107 -0
- package/scripts/music/gen/sfx_build.py +332 -0
- package/scripts/music/gen/sfx_merge.py +255 -0
- package/scripts/music/gen/sfx_minimax.py +61 -0
- package/scripts/music/gen/sfx_nalati.py +331 -0
- package/scripts/music/gen/sfx_sprite.py +424 -0
- package/scripts/music/gen/stems.py +539 -0
- package/scripts/music/gen/test_loop_meter.py +29 -0
- package/scripts/music/gen/test_ob7_provenance.py +77 -0
- package/scripts/music/gen/v3-folk-build.json +148 -0
- package/scripts/music/gen/v3-folk.json +1818 -0
- package/scripts/music/gen/v3-jobs.json +145 -0
- package/scripts/music/gen/v3-orchestral-build.json +148 -0
- package/scripts/music/gen/v3-orchestral.json +1813 -0
- package/scripts/music/gen/v3-ph-folk-build.json +94 -0
- package/scripts/music/gen/v3-ph-folk.json +1806 -0
- package/scripts/music/gen/v3-ph-orchestral-build.json +94 -0
- package/scripts/music/gen/v3-ph-orchestral.json +1824 -0
- package/scripts/music/gen/v3-ph-piano-build.json +94 -0
- package/scripts/music/gen/v3-ph-piano.json +1818 -0
- package/scripts/music/gen/v3-piano-build.json +148 -0
- package/scripts/music/gen/v3-piano.json +1813 -0
- package/scripts/music/wildshard-theme.mid +0 -0
- package/scripts/music/wildshard-trailer30.mid +0 -0
- package/scripts/named-blob-output.d.mts +8 -0
- package/scripts/named-blob-output.mjs +48 -0
- package/scripts/pack-all.mjs +15 -0
- package/scripts/pid-lock.d.mts +1 -0
- package/scripts/pid-lock.mjs +63 -0
- package/scripts/practice/bake_dummy.py +53 -0
- package/scripts/practice/build_dummies.sh +43 -0
- package/scripts/practice/dummy_parts.py +568 -0
- package/scripts/practice/dummy_rig_gate.py +139 -0
- package/scripts/practice/gate_sheet.py +36 -0
- package/scripts/practice/generate_dummy_unimate.py +132 -0
- package/scripts/practice/pack_dummy.mjs +59 -0
- package/scripts/practice/repair_dummy_weights.mjs +68 -0
- package/scripts/practice/rig_dummy.py +828 -0
- package/scripts/practice/verify_unimate_skin.mjs +356 -0
- package/scripts/preparation-seed.mjs +15 -0
- package/scripts/prepare-basis-tool.mjs +6 -0
- package/scripts/prepare-product.d.mts +14 -0
- package/scripts/prepare-product.mjs +101 -0
- package/scripts/product-build-tools.d.mts +3 -0
- package/scripts/product-build-tools.json +3 -0
- package/scripts/product-build-tools.mjs +31 -0
- package/scripts/publish-public.mjs +7 -0
- package/scripts/push-tables.d.mts +1 -0
- package/scripts/push-tables.mjs +28 -0
- package/scripts/record-shard-mounts.mjs +133 -0
- package/scripts/sdk-externals.d.mts +2 -0
- package/scripts/sdk-externals.mjs +2 -0
- package/scripts/section-inventory.ts +209 -0
- package/scripts/select-candidate.mjs +15 -0
- package/scripts/shard-build-pool.d.mts +4 -0
- package/scripts/shard-build-pool.mjs +53 -0
- package/scripts/shard-line-baseline.json +17 -0
- package/scripts/shard-milestones.d.mts +15 -0
- package/scripts/shard-milestones.mjs +105 -0
- package/scripts/shard-output-report.d.mts +9 -0
- package/scripts/shard-output-report.mjs +85 -0
- package/scripts/shard-platform-cli.mjs +93 -0
- package/scripts/shard-progress.mjs +212 -0
- package/scripts/shard-timelapse.py +102 -0
- package/scripts/shardfile-cold-boot.mjs +79 -0
- package/scripts/shardfile-vite.d.mts +4 -0
- package/scripts/shardfile-vite.mjs +20 -0
- package/scripts/simplify-models.mjs +24 -0
- package/scripts/site-facts.mjs +88 -0
- package/scripts/test-template-gate.mjs +44 -0
- package/scripts/test_golden_compare.py +68 -0
- package/scripts/tex-tiers.cache.json +181 -0
- package/scripts/tex-tiers.mjs +240 -0
- package/scripts/texmem-probe.mjs +184 -0
- package/scripts/unused-assets.mjs +173 -0
- package/scripts/vite-tmp.d.mts +23 -0
- package/scripts/vite-tmp.mjs +157 -0
- package/scripts/wave-line-baselines.json +32 -0
- package/scripts/wildshard.d.mts +4 -0
- package/scripts/wildshard.mjs +105 -0
- package/scripts/witness-checkpoints.d.mts +10 -0
- package/scripts/witness-checkpoints.mjs +84 -0
- package/scripts/witness-generation.d.mts +10 -0
- package/scripts/witness-generation.mjs +45 -0
- package/scripts/witness-manifests.d.mts +8 -0
- package/scripts/witness-manifests.mjs +157 -0
- package/scripts/worktree-ignore.d.mts +4 -0
- package/scripts/worktree-ignore.mjs +36 -0
- package/scripts/worktree-reap.mjs +214 -0
- package/scripts/worktree.mjs +396 -0
- package/scripts/worldclaw/capture-front.sh +28 -0
- package/scripts/worldclaw/design-template.md +62 -0
- package/scripts/worldclaw/spec-map.py +92 -0
- package/scripts/worldclaw/spec.ts +96 -0
- package/skills/wildshard/SKILL.md +50 -0
- package/skills/wildshard-goldens/SKILL.md +54 -0
- package/skills/wildshard-mockup-to-model/SKILL.md +56 -0
- package/skills/wildshard-upgrade/SKILL.md +47 -0
- package/src/.oxfmtrc.json +50 -0
- package/src/.oxlintrc.json +173 -0
- package/src/cli/account/account.ts +199 -0
- package/src/cli/account/command.ts +193 -0
- package/src/cli/account/key.ts +154 -0
- package/src/cli/args.ts +97 -0
- package/src/cli/audio/audio.ts +39 -0
- package/src/cli/bin.mjs +8 -0
- package/src/cli/delete/delete.ts +258 -0
- package/src/cli/help.ts +204 -0
- package/src/cli/hero/adopt.ts +103 -0
- package/src/cli/hero/hero.ts +112 -0
- package/src/cli/hero/stamp.ts +298 -0
- package/src/cli/main.ts +291 -0
- package/src/cli/report.ts +20 -0
- package/src/cli/shardfile/command.ts +49 -0
- package/src/cli/shardfile/shardfile.ts +192 -0
- package/src/cli/upload/api.ts +246 -0
- package/src/cli/upload/compress.ts +55 -0
- package/src/cli/upload/hero.ts +62 -0
- package/src/cli/upload/placement.ts +115 -0
- package/src/cli/upload/provenance.ts +192 -0
- package/src/cli/upload/signature.ts +30 -0
- package/src/cli/upload/upload.ts +269 -0
- package/src/cli/upload/validate.ts +74 -0
- package/src/cli/upload/wire.ts +147 -0
- package/src/cli/version.ts +63 -0
- package/src/commons/bake/portableMath.ts +187 -0
- package/src/commons/catalogue.ts +10 -0
- package/src/commons/courseProgram.ts +32 -0
- package/src/commons/practiceCourse.ts +16 -0
- package/src/commons/scripts/abi.as +14 -0
- package/src/commons/scripts/bridge.as +14 -0
- package/src/commons/scripts/course.as +63 -0
- package/src/scripts/ask-new.sh +29 -0
- package/src/scripts/asks.mjs +141 -0
- package/src/scripts/herdr-prompt.sh +34 -0
- package/src/scripts/herdr-question-open.sh +67 -0
- package/src/scripts/md-wrap.mjs +229 -0
- package/src/server/app.ts +19 -0
- package/src/server/serve.ts +49 -0
- package/src/sharddev/admission.ts +7 -0
- package/src/sharddev/agentFiles.ts +127 -0
- package/src/sharddev/arenaView.ts +15 -0
- package/src/sharddev/as/groupBankV2.ts +36 -0
- package/src/sharddev/as/groupStepV2.ts +13 -0
- package/src/sharddev/as/ws.ts +30 -0
- package/src/sharddev/as/wsV2.ts +180 -0
- package/src/sharddev/assemblyscriptCompiler.d.mts +5 -0
- package/src/sharddev/assemblyscriptCompiler.mjs +14 -0
- package/src/sharddev/assetHandle.ts +84 -0
- package/src/sharddev/assetOwner.ts +70 -0
- package/src/sharddev/assetScope.ts +30 -0
- package/src/sharddev/assets.ts +21 -0
- package/src/sharddev/audio.ts +9 -0
- package/src/sharddev/audioEncode.ts +211 -0
- package/src/sharddev/author.ts +3 -0
- package/src/sharddev/authorError.ts +28 -0
- package/src/sharddev/authorManifest.ts +39 -0
- package/src/sharddev/bake/annulus.ts +19 -0
- package/src/sharddev/bake/assemblyscriptMemo.ts +76 -0
- package/src/sharddev/bake/assemblyscriptMemoPort.ts +4 -0
- package/src/sharddev/bake/authoredWorld.ts +201 -0
- package/src/sharddev/bake/basisEncoder.ts +95 -0
- package/src/sharddev/bake/basisGlb.ts +85 -0
- package/src/sharddev/bake/basisTool.ts +74 -0
- package/src/sharddev/bake/basisToolInputs.ts +476 -0
- package/src/sharddev/bake/byteCodec.ts +33 -0
- package/src/sharddev/bake/canvasAtlas.ts +406 -0
- package/src/sharddev/bake/coarseCopy.ts +59 -0
- package/src/sharddev/bake/colliders.ts +87 -0
- package/src/sharddev/bake/compactGlb.ts +224 -0
- package/src/sharddev/bake/compileScript.ts +119 -0
- package/src/sharddev/bake/compileScriptV2.ts +75 -0
- package/src/sharddev/bake/contactRows.ts +84 -0
- package/src/sharddev/bake/creaturePlacement.ts +117 -0
- package/src/sharddev/bake/export.ts +67 -0
- package/src/sharddev/bake/facetedGeometry.ts +379 -0
- package/src/sharddev/bake/farImpostor.ts +120 -0
- package/src/sharddev/bake/forest.ts +100 -0
- package/src/sharddev/bake/format-hook.mjs +2 -0
- package/src/sharddev/bake/generatorGlb.ts +23 -0
- package/src/sharddev/bake/geometryBounds.ts +77 -0
- package/src/sharddev/bake/geometryError.ts +48 -0
- package/src/sharddev/bake/glb.ts +355 -0
- package/src/sharddev/bake/glbCompression.ts +143 -0
- package/src/sharddev/bake/gltfSource.ts +59 -0
- package/src/sharddev/bake/groundMap.ts +142 -0
- package/src/sharddev/bake/image.ts +20 -0
- package/src/sharddev/bake/isleMap.ts +64 -0
- package/src/sharddev/bake/json.mjs +84 -0
- package/src/sharddev/bake/keyedSky.ts +47 -0
- package/src/sharddev/bake/keyedSkyMemo.ts +39 -0
- package/src/sharddev/bake/kinds.ts +137 -0
- package/src/sharddev/bake/lightSources.ts +31 -0
- package/src/sharddev/bake/mapAssembly.ts +84 -0
- package/src/sharddev/bake/mapRaster.ts +173 -0
- package/src/sharddev/bake/mapRest.ts +57 -0
- package/src/sharddev/bake/mapScenes.ts +234 -0
- package/src/sharddev/bake/materialGraph.ts +32 -0
- package/src/sharddev/bake/meadow.ts +27 -0
- package/src/sharddev/bake/meshoptChoiceMemo.ts +34 -0
- package/src/sharddev/bake/nativeInteractionFacts.ts +5 -0
- package/src/sharddev/bake/nativeLattice.ts +178 -0
- package/src/sharddev/bake/nativeRaster.ts +106 -0
- package/src/sharddev/bake/nativeTerrainField.ts +11 -0
- package/src/sharddev/bake/navigation-json.mjs +38 -0
- package/src/sharddev/bake/navigation.ts +113 -0
- package/src/sharddev/bake/navigationAsset.ts +18 -0
- package/src/sharddev/bake/nearPlaceholder.ts +206 -0
- package/src/sharddev/bake/normalizeRig.ts +80 -0
- package/src/sharddev/bake/phoneAstc.ts +93 -0
- package/src/sharddev/bake/placeholders.ts +581 -0
- package/src/sharddev/bake/placement.ts +80 -0
- package/src/sharddev/bake/portableBytes.ts +18 -0
- package/src/sharddev/bake/portableBytesMemo.ts +50 -0
- package/src/sharddev/bake/practiceCourse.ts +49 -0
- package/src/sharddev/bake/primitives.ts +96 -0
- package/src/sharddev/bake/props.ts +443 -0
- package/src/sharddev/bake/questPlacement.ts +98 -0
- package/src/sharddev/bake/rawTexture.ts +26 -0
- package/src/sharddev/bake/riderArms.ts +97 -0
- package/src/sharddev/bake/rig.ts +95 -0
- package/src/sharddev/bake/riggedHullRecipes.ts +40 -0
- package/src/sharddev/bake/signPlacements.ts +25 -0
- package/src/sharddev/bake/simplifier.ts +52 -0
- package/src/sharddev/bake/skinned.ts +312 -0
- package/src/sharddev/bake/slabChunks.ts +149 -0
- package/src/sharddev/bake/slabs.ts +263 -0
- package/src/sharddev/bake/source-loader.mjs +55 -0
- package/src/sharddev/bake/sourceMetadata.ts +54 -0
- package/src/sharddev/bake/species.ts +368 -0
- package/src/sharddev/bake/specimenCatalogue.ts +47 -0
- package/src/sharddev/bake/splatGround.ts +141 -0
- package/src/sharddev/bake/staticMaterials.ts +171 -0
- package/src/sharddev/bake/terrain.ts +195 -0
- package/src/sharddev/bake/texture.ts +33 -0
- package/src/sharddev/bake/textureWasm.ts +81 -0
- package/src/sharddev/bake/tileEncoder.ts +11 -0
- package/src/sharddev/bake/tileGrid.ts +62 -0
- package/src/sharddev/bake/v2Finite.ts +160 -0
- package/src/sharddev/bake/v2Fuel.ts +71 -0
- package/src/sharddev/bake/wholePartition.ts +74 -0
- package/src/sharddev/bake/wholePieceJoin.ts +147 -0
- package/src/sharddev/bake/world.ts +173 -0
- package/src/sharddev/bake/worldCollision.ts +128 -0
- package/src/sharddev/bake/worldGeometry.ts +237 -0
- package/src/sharddev/bake/worldGlb.ts +123 -0
- package/src/sharddev/bake/worldImage.ts +12 -0
- package/src/sharddev/bake/worldLod.ts +128 -0
- package/src/sharddev/bake/worldRows.ts +102 -0
- package/src/sharddev/bake/worldTextureMemo.ts +63 -0
- package/src/sharddev/bake/zstdBytesMemo.ts +52 -0
- package/src/sharddev/bake.ts +193 -0
- package/src/sharddev/bakePublication.ts +31 -0
- package/src/sharddev/behaviourSource.ts +94 -0
- package/src/sharddev/bin/wildshard.mjs +7 -0
- package/src/sharddev/blobBytes.ts +65 -0
- package/src/sharddev/blobs.ts +138 -0
- package/src/sharddev/bootInventory.ts +129 -0
- package/src/sharddev/bossProfiles.ts +18 -0
- package/src/sharddev/buildBehaviour.ts +77 -0
- package/src/sharddev/buildCacheMetrics.ts +17 -0
- package/src/sharddev/buildDecisionScripts.ts +122 -0
- package/src/sharddev/check.ts +118 -0
- package/src/sharddev/checkProject.ts +127 -0
- package/src/sharddev/cli.ts +200 -0
- package/src/sharddev/clientChannels.ts +169 -0
- package/src/sharddev/clientScripts.ts +10 -0
- package/src/sharddev/commons.ts +77 -0
- package/src/sharddev/commonsCosts.ts +11 -0
- package/src/sharddev/compileMovers.ts +11 -0
- package/src/sharddev/configBoundary.ts +6 -0
- package/src/sharddev/cookInput.ts +40 -0
- package/src/sharddev/crowds.ts +6 -0
- package/src/sharddev/decisionBindingMap.ts +11 -0
- package/src/sharddev/decisionScriptBindings.ts +117 -0
- package/src/sharddev/decisionScripts.ts +28 -0
- package/src/sharddev/decisionSource.ts +51 -0
- package/src/sharddev/dev.ts +113 -0
- package/src/sharddev/director.ts +26 -0
- package/src/sharddev/directorAbi.ts +77 -0
- package/src/sharddev/discoveryDocument.ts +97 -0
- package/src/sharddev/draft.ts +11 -0
- package/src/sharddev/eliteEntryRows.ts +29 -0
- package/src/sharddev/entries.ts +76 -0
- package/src/sharddev/entryReads.ts +73 -0
- package/src/sharddev/executeBundle.ts +55 -0
- package/src/sharddev/finds.ts +5 -0
- package/src/sharddev/formatJsonSchema.ts +3 -0
- package/src/sharddev/generationCache.ts +257 -0
- package/src/sharddev/generationRecipe.ts +94 -0
- package/src/sharddev/handwritten.ts +110 -0
- package/src/sharddev/immutable.ts +14 -0
- package/src/sharddev/interactions.ts +38 -0
- package/src/sharddev/kit/bakedGeometry.ts +16 -0
- package/src/sharddev/kit/geometryPack.ts +110 -0
- package/src/sharddev/ledger.ts +13 -0
- package/src/sharddev/looks/tileField.ts +67 -0
- package/src/sharddev/materialGraphFiles.ts +57 -0
- package/src/sharddev/materials.ts +574 -0
- package/src/sharddev/measure.ts +18 -0
- package/src/sharddev/modes.ts +115 -0
- package/src/sharddev/moverPrograms.ts +213 -0
- package/src/sharddev/movers.ts +75 -0
- package/src/sharddev/nativePopulationRows.ts +46 -0
- package/src/sharddev/newProject.ts +226 -0
- package/src/sharddev/noise.ts +54 -0
- package/src/sharddev/outputProduct.ts +188 -0
- package/src/sharddev/outputRuntime.ts +66 -0
- package/src/sharddev/performancePolicy.ts +29 -0
- package/src/sharddev/phasedBoss.ts +34 -0
- package/src/sharddev/physics.ts +194 -0
- package/src/sharddev/platformSections.ts +42 -0
- package/src/sharddev/plumbing.ts +8 -0
- package/src/sharddev/productOutput.ts +128 -0
- package/src/sharddev/project.ts +337 -0
- package/src/sharddev/projectCompilerIdentity.ts +94 -0
- package/src/sharddev/projectDecisions.ts +66 -0
- package/src/sharddev/projectEntryProof.ts +32 -0
- package/src/sharddev/projectGeneration.ts +219 -0
- package/src/sharddev/projectInputFiles.ts +47 -0
- package/src/sharddev/projectManifest.ts +108 -0
- package/src/sharddev/projectMap.ts +35 -0
- package/src/sharddev/projectOutput.ts +242 -0
- package/src/sharddev/projectPolicy.ts +17 -0
- package/src/sharddev/projectSections.ts +27 -0
- package/src/sharddev/questGraph.ts +25 -0
- package/src/sharddev/quests.ts +65 -0
- package/src/sharddev/random.ts +61 -0
- package/src/sharddev/refusals.ts +304 -0
- package/src/sharddev/reportCard.ts +13 -0
- package/src/sharddev/returnProjectionV2.ts +81 -0
- package/src/sharddev/rows.ts +192 -0
- package/src/sharddev/runtimeImports.ts +38 -0
- package/src/sharddev/runtimeMirrors.ts +39 -0
- package/src/sharddev/runtimePerformance.ts +38 -0
- package/src/sharddev/scene.ts +321 -0
- package/src/sharddev/sceneAnimation.ts +54 -0
- package/src/sharddev/sceneAudio.ts +64 -0
- package/src/sharddev/sceneDeclarations.ts +100 -0
- package/src/sharddev/sceneGraph.ts +139 -0
- package/src/sharddev/sceneTransform.ts +12 -0
- package/src/sharddev/schemaValidation.ts +61 -0
- package/src/sharddev/sections.ts +47 -0
- package/src/sharddev/shardSource.ts +59 -0
- package/src/sharddev/sourceReader.ts +26 -0
- package/src/sharddev/spawns.ts +38 -0
- package/src/sharddev/species/clips.ts +24 -0
- package/src/sharddev/species.ts +29 -0
- package/src/sharddev/speciesBrains.ts +19 -0
- package/src/sharddev/synth.ts +66 -0
- package/src/sharddev/test/compileDualScriptV2.ts +71 -0
- package/src/sharddev/test/compileSimV2.ts +21 -0
- package/src/sharddev/test/diskScriptScenario.ts +86 -0
- package/src/sharddev/test/scriptScenario.ts +249 -0
- package/src/sharddev/test/scriptSource.ts +12 -0
- package/src/sharddev/version.ts +4 -0
- package/src/sharddev/weapons/bowProfile.ts +20 -0
- package/src/sharddev/weapons/firearmRows.ts +11 -0
- package/src/sharddev/weapons/meleeProfile.ts +71 -0
- package/src/sharddev/weapons/thrownProfile.ts +10 -0
- package/src/sharddev/worldScenes.ts +308 -0
- package/src/sharddev/worldSource.ts +82 -0
- package/src/shards/_template/README.md +78 -0
- package/src/shards/_template/assets/2bf489fdb15f1734ddb4c4f32d500ec6da85c765ec7a4eb28dc6781160e7ec8c +0 -0
- package/src/shards/_template/assets/97ec4d8f75f5fa6239ee919444d6dc19fd35896bb305930c1f050ac6e0e0e6a6 +1 -0
- package/src/shards/_template/assets/a6a587a31327f936b1b04c05ade818c73fc8964260918662db43539465e27586 +0 -0
- package/src/shards/_template/assets/b4fbde0422e125b498c3dc8b9a5cc2516c8598f09e9d0e5f6b639b32f98179e6 +0 -0
- package/src/shards/_template/assets/bfa4dfc9c18979f904557ee8deab0058b8a399be10266f5fb1578b403f482fd4 +1 -0
- package/src/shards/_template/assets/ef3b7ff4fd22715771cb7d68a3977a903c5e7c3dc293542687d04b3ef3ace2cb +0 -0
- package/src/shards/_template/assets/f2db05998615ce1cb79ea96be32c168842eb6a2b34ec01feb86d36404603ee54 +0 -0
- package/src/shards/_template/assets/fef98ebb7fce6f66b26e78ac699e5c90f9bdcfaf8cabeb2b58125347eea8b4ab +0 -0
- package/src/shards/_template/behaviour/boss.as +39 -0
- package/src/shards/_template/behaviour/door.as +32 -0
- package/src/shards/_template/behaviour/hooks.json +129 -0
- package/src/shards/_template/behaviour/idle.as +75 -0
- package/src/shards/_template/behaviour/items.as +22 -0
- package/src/shards/_template/card/landscape.jpg +0 -0
- package/src/shards/_template/card/portrait.jpg +0 -0
- package/src/shards/_template/card/thumb.jpg +0 -0
- package/src/shards/_template/data/audio.json +45 -0
- package/src/shards/_template/data/bossDecision.json +83 -0
- package/src/shards/_template/data/budgets.json +70 -0
- package/src/shards/_template/data/card.json +281 -0
- package/src/shards/_template/data/clientScripts.json +987 -0
- package/src/shards/_template/data/creatures.json +65 -0
- package/src/shards/_template/data/director.json +39 -0
- package/src/shards/_template/data/encounters.json +96 -0
- package/src/shards/_template/data/items.json +172 -0
- package/src/shards/_template/data/layout.json +66 -0
- package/src/shards/_template/data/ledger.json +32 -0
- package/src/shards/_template/data/look.json +521 -0
- package/src/shards/_template/data/map.json +64 -0
- package/src/shards/_template/data/moves.json +16 -0
- package/src/shards/_template/data/placeholder.json +8 -0
- package/src/shards/_template/data/plumbing.json +32 -0
- package/src/shards/_template/data/quests.json +223 -0
- package/src/shards/_template/data/rows.json +423 -0
- package/src/shards/_template/data/skins.json +66 -0
- package/src/shards/_template/data/spawn.json +6 -0
- package/src/shards/_template/data/targets.json +150 -0
- package/src/shards/_template/data/text.json +12 -0
- package/src/shards/_template/data/ui.json +33 -0
- package/src/shards/_template/data/water.json +13 -0
- package/src/shards/_template/generators/behaviour.ts +34 -0
- package/src/shards/_template/generators/boss.ts +29 -0
- package/src/shards/_template/generators/buildOptions.ts +2 -0
- package/src/shards/_template/generators/cell.ts +224 -0
- package/src/shards/_template/generators/districts.ts +215 -0
- package/src/shards/_template/generators/farLook.ts +15 -0
- package/src/shards/_template/generators/generate.ts +27 -0
- package/src/shards/_template/generators/ground.ts +15 -0
- package/src/shards/_template/generators/kit.ts +69 -0
- package/src/shards/_template/generators/landscape.ts +59 -0
- package/src/shards/_template/generators/landscapeNoise.ts +62 -0
- package/src/shards/_template/generators/mapInputs.ts +10 -0
- package/src/shards/_template/generators/product.ts +100 -0
- package/src/shards/_template/generators/productOutput.ts +18 -0
- package/src/shards/_template/generators/props.ts +9 -0
- package/src/shards/_template/generators/templatePropsSource.ts +58 -0
- package/src/shards/_template/generators/terrain.ts +17 -0
- package/src/shards/_template/generators/world.ts +630 -0
- package/src/shards/_template/hero.json +10 -0
- package/src/shards/_template/look/entry-reads.json +20 -0
- package/src/shards/_template/manifest.json +281 -0
- package/src/shards/_template/shard.config.ts +10 -0
- package/src/shared/health.ts +10 -0
- package/src/tools/build-web.ts +59 -0
- package/src/tsconfig.json +30 -0
- package/src/web/app.tsx +53 -0
- package/src/web/index.html +12 -0
- package/src/web/main.tsx +10 -0
- package/src/web/tsconfig.json +13 -0
- package/tsconfig.author.json +23 -0
- package/tsconfig.commons.json +21 -0
- package/tsconfig.json +47 -0
- package/tsconfig.sharddev.json +20 -0
package/GUIDE.md
ADDED
|
@@ -0,0 +1,895 @@
|
|
|
1
|
+
# The shard author's guide
|
|
2
|
+
|
|
3
|
+
> Written by: Claude
|
|
4
|
+
|
|
5
|
+
> **State:** living, 2026-11-13, sharddev `@wildshard/sdk` 0.2.x (SHARD-AUTHORING SA13). This file ships in the
|
|
6
|
+
> package and `wildshard new` copies it into every new project. Steps marked **not built yet** name the plan row
|
|
7
|
+
> (meta repo `docs/plans/SHARD-AUTHORING-PLAN.md`) that builds them; until then, do what that step says instead.
|
|
8
|
+
|
|
9
|
+
This guide is for people and agents making a Wildshard shard. Read sections 1 and 2 first; use the rest when you need
|
|
10
|
+
it. Facts that change with every release (each budget's number, each command's flags) are not copied here: each one
|
|
11
|
+
names the command or page that prints it. Only limits a decision fixed, such as the audio budget (J303), are written in.
|
|
12
|
+
|
|
13
|
+
**Words.** A **shard source** is your folder: data, generators, scripts and assets. **Build** turns the shard source
|
|
14
|
+
into a **shard file** (`<slug>.shardfile`), the one file you upload. **Bake** is the part of build that turns parts of
|
|
15
|
+
the shard source into data (maps, colliders, compiled scripts). **Upload** sends a shard file to the Wildshard API for a
|
|
16
|
+
**channel**, `--channel staging` or `--channel prod`; section 5 shows which of the three sites (preview, staging,
|
|
17
|
+
production) each one moves. The **hero** is the shard's card: three images (thumb, portrait,
|
|
18
|
+
landscape) shown on SHARD SELECT. A **budget** is a limit on what the shard costs a player (section 3). A **refusal**
|
|
19
|
+
is a command stopping with a rule id, a fix and a link into section 6.
|
|
20
|
+
|
|
21
|
+
**Running `wildshard` today.** The real `@wildshard/sdk` is not on npm yet: the npm copy is a README-only placeholder
|
|
22
|
+
(NPM-PUBLISH NP4 publishes the real one). Until then, run the CLI from a checkout of
|
|
23
|
+
`github.com/project-wildshard/sharddev`, for example `alias wildshard='node /path/to/sharddev/bin/wildshard.mjs'`.
|
|
24
|
+
This guide writes `wildshard <verb>`. `wildshard --help` lists every verb; `wildshard <verb> --help` prints one.
|
|
25
|
+
`wildshard --version` prints the sdk, engine, shard-format and `three` versions. `new` writes a `package.json` that pins
|
|
26
|
+
`@wildshard/sdk`, shard-format, engine and `three` exactly; once the sdk is on npm, `pnpm install` then
|
|
27
|
+
`pnpm exec wildshard <verb>` runs the copy it pins. Add npm packages of your own with `pnpm add <name>`.
|
|
28
|
+
|
|
29
|
+
## 1. The loop
|
|
30
|
+
|
|
31
|
+
The loop is: `new`, `dev`, `check`, `hero`, `upload --channel staging`, then `upload --channel prod`, then share the
|
|
32
|
+
link. Run each command from the project folder. `.` names the project: commands find its shard source at `src/` (or a
|
|
33
|
+
repo's one `src/shards/<slug>/`).
|
|
34
|
+
|
|
35
|
+
| # | Step | Command | Today |
|
|
36
|
+
|---|---|---|---|
|
|
37
|
+
| 1 | Start | `wildshard new my-shard` | Works. Writes a shard repo in `my-shard/`: the reference world (Template 1, Mossgate) as its shard source at `src/`, plus `package.json`, `tsconfig.json`, `.gitignore`, `.npmrc`, a README, this guide, the four `wildshard` skills and the agent files (`AGENTS.md`, `CLAUDE.md`, `.agents/skills/`) |
|
|
38
|
+
| 2 | Walk it | `wildshard dev .` | **Not built yet (SA15).** See "Walking your shard" below |
|
|
39
|
+
| 3 | Check | `wildshard check .` | Works: lint, build, validate, prove and the report card, one verdict |
|
|
40
|
+
| 4 | Hero | `wildshard hero . --base <url>` | Works only with an engine checkout: it needs your shard in a served engine build. See "The hero" below |
|
|
41
|
+
| 5 | Prepare | `wildshard prepare public/shardfiles/my-shard --base <url>`, then `wildshard build public/shardfiles/my-shard` | Works only with an engine checkout. See "Uploading" below |
|
|
42
|
+
| 6 | Upload to staging | `wildshard upload public/shardfiles/my-shard.shardfile --channel staging --version 0.0.1` | Works only for the Wildshard team today: it needs the team's creator key. See "Uploading" below |
|
|
43
|
+
| 7 | Upload to production | the same with `--channel prod` and a higher version | The same. Try staging first |
|
|
44
|
+
| 8 | Share | `https://staging.wildshard.io/slug/my-shard` | **Not built yet (SA36, SA37).** See section 5 |
|
|
45
|
+
|
|
46
|
+
`check` is the one verb to run after every change: it runs `build`, `validate` and `prove` for you. The one separate
|
|
47
|
+
`build` in the loop is `build <folder>` after `prepare`. Done when the last line reads `check pass in N s` (exit code
|
|
48
|
+
0); `check fail` lists each refusal. `wildshard check . --json` prints one JSON document (verdict, steps, refusals
|
|
49
|
+
with `rule`, `fix` and `guide`) for agents and scripts.
|
|
50
|
+
|
|
51
|
+
### Every verb
|
|
52
|
+
|
|
53
|
+
| Verb | What it is for |
|
|
54
|
+
|---|---|
|
|
55
|
+
| `wildshard new <dir> [slug] [--template sdk\|blender] [--empty]` | Start a shard repo in a folder that does not exist yet, its shard source at `src/`. The slug is the folder's name unless you give one. `--template sdk` (the default) copies the reference world; `--template blender` copies the hand-written Blender template (below); any other template refuses before writing. `--empty` writes a bare shard source instead of the reference world |
|
|
56
|
+
| `wildshard update [dir]` | Rewrite this guide and the four `wildshard` skills from the installed sdk, after you move to a newer one (section 7) |
|
|
57
|
+
| `wildshard dev <source>` | Serve the shard source on localhost and rebuild on every save (section 4). **Not built yet** for an installed sdk (SA15) |
|
|
58
|
+
| `wildshard check <source> [folder] [--json]` | The loop's check: lint, build, validate, prove, report card, verdict |
|
|
59
|
+
| `wildshard hero <source> --base <url>` | Capture the hero from a served build and stamp `hero.json`. `--stamp-existing` marks the images already there as current: only when you have looked at them and they show the current world |
|
|
60
|
+
| `wildshard upload <file> --channel staging\|prod` | Send a prepared shard file to the API (section 5) |
|
|
61
|
+
| `wildshard account <email>` | Make your account once and save its key, which upload sends (see "Uploading", step 5) |
|
|
62
|
+
| `wildshard whoami` | Say which account key upload would send (from `WILDSHARD_API_KEY` or the key file), show its first characters, and print its account's email and how many slugs it owns (`--server` or `WILDSHARD_API_URL`) |
|
|
63
|
+
| `wildshard delete <slug> [--yes]` | Delete your shard from the catalogue, every channel and the grid, after you type its slug (see "Deleting a shard") |
|
|
64
|
+
| `wildshard build <source>` | Build alone: bake the shard source into `public/shardfiles/<slug>/` and write `public/shardfiles/<slug>.shardfile`. `wildshard build <folder>` writes the shard file of a built folder (after `prepare`) |
|
|
65
|
+
| `wildshard prepare <folder> --base <url>` | Record the built folder in phone WebKit against an exact engine preview, which turns a draft into the uploadable form (see "Uploading") |
|
|
66
|
+
| `wildshard validate <source \| folder>` | Shard-format's checks and the headless budget run, alone |
|
|
67
|
+
| `wildshard prove <source> <proof.json>` | Play a proof tape headlessly and print what happened |
|
|
68
|
+
| `wildshard synth <source>` | Run `shard.config.ts`'s scene exports and write the scene as data |
|
|
69
|
+
| `wildshard schema [list\|shardfile\|<root>] [pointer]` | Print the JSON Schema of the shard file, or of one section or field |
|
|
70
|
+
| `wildshard serve` | The sharddev web app on localhost (tools for this repo, not for your shard) |
|
|
71
|
+
| `wildshard build-shards` | Build every shard source under a repo's `src/shards/` (repos holding several shards) |
|
|
72
|
+
| `wildshard pack <folder>` | Old name for `wildshard build <folder>`; use `build` |
|
|
73
|
+
|
|
74
|
+
### Walking your shard
|
|
75
|
+
|
|
76
|
+
`wildshard dev .` is how you will walk a shard on your machine: it serves the shard on localhost and reloads the page
|
|
77
|
+
when you save. It is **not built yet (SA15)**: today it stops with "wildshard dev requires the SDK devserver client",
|
|
78
|
+
also from a sharddev checkout. Engine has to publish the dev client first (HOW-WE-BUILD ENG-16, then SD-2).
|
|
79
|
+
|
|
80
|
+
Until then there are two ways to walk a shard, and neither works from this folder alone:
|
|
81
|
+
|
|
82
|
+
- **In an engine checkout:** build an engine preview that carries your built shard file folder, then enter it from
|
|
83
|
+
SHARD SELECT. These steps are not written down for authors yet (HOW-WE-BUILD F5 writes them, in sharddev
|
|
84
|
+
`docs/second-machine.md`): ask the Wildshard team.
|
|
85
|
+
- **On staging, after an upload:** only once the Wildshard team has placed the shard on the grid (section 5).
|
|
86
|
+
|
|
87
|
+
What you can do from this folder alone: `wildshard check .` builds the shard, runs it headlessly against its budgets
|
|
88
|
+
and, with a `proof.json` tape, plays its quests headlessly (`prove`).
|
|
89
|
+
|
|
90
|
+
### The hero
|
|
91
|
+
|
|
92
|
+
The hero is three images: thumb 640x360, portrait 804x1626 and landscape 1600x900. `wildshard new` gives your shard a
|
|
93
|
+
generated card (a `data:` image) so it has one from the start. Build accepts that card with a note. To capture a real
|
|
94
|
+
hero:
|
|
95
|
+
|
|
96
|
+
1. Point `card.thumb`, `card.portrait` and `card.landscape` in `manifest.json` at image files inside the shard source
|
|
97
|
+
(for example `card/thumb.jpg`). Hero capture refuses a `data:` card.
|
|
98
|
+
2. Serve an engine build that carries this exact shard (see "Walking your shard": an engine checkout today).
|
|
99
|
+
3. Run `wildshard hero . --base <served-build-url>`. It opens the build in headless Chromium, enters your shard from
|
|
100
|
+
SHARD SELECT, shoots the view `hero.json`'s `camera` names (or the spawn view), writes the three files and stamps
|
|
101
|
+
`hero.json` with a hash of your content.
|
|
102
|
+
|
|
103
|
+
Build then refuses a shard file whose content changed after the hero was stamped (`hero-stale`), and upload refuses a
|
|
104
|
+
new version whose hero is the same as the previous version's (`hero-unchanged`). Section 6 has every hero refusal.
|
|
105
|
+
|
|
106
|
+
### Uploading
|
|
107
|
+
|
|
108
|
+
An upload sends one shard file to the API (`https://api.wildshard.io`) and names its channel. Do these in order,
|
|
109
|
+
before every upload:
|
|
110
|
+
|
|
111
|
+
1. **Hero.** A new version needs a new hero (J306). After your last change to the world, capture one
|
|
112
|
+
(`wildshard hero . --base <url>`, "The hero" above). Done when `hero.json` and the three card images are rewritten.
|
|
113
|
+
2. **Commit.** Upload names the commit the bytes came from and refuses uncommitted changes to tracked files. The first
|
|
114
|
+
time: `git init`, then commit (the `.gitignore` `new` wrote keeps `public/shardfiles/` and `node_modules/` out).
|
|
115
|
+
Every time: commit everything, the hero included. Done when `git status` is clean.
|
|
116
|
+
3. **Check.** `wildshard check .` builds the shard file. It is a **draft** (`sdk: "0.2"`): check prints a
|
|
117
|
+
`shardfile-draft` warning, and upload and the API refuse a draft. Done at `check pass`.
|
|
118
|
+
4. **Prepare.** `wildshard prepare public/shardfiles/<slug> --base <url>`, with the URL of an exact engine preview made
|
|
119
|
+
for preparation, turns the draft into the uploadable form (`sdk: "0.3"`). Then `wildshard build
|
|
120
|
+
public/shardfiles/<slug>` writes the prepared shard file. That preview comes from an engine checkout today, so an
|
|
121
|
+
author outside the Wildshard team cannot prepare yet: the steps are not written down for authors (HOW-WE-BUILD F5);
|
|
122
|
+
ask the Wildshard team.
|
|
123
|
+
5. **Keys.** Set `WILDSHARD_API_URL=https://api.wildshard.io` (or pass `--server`) and
|
|
124
|
+
`WILDSHARD_CREATOR_PRIVATE_KEY`, the base64 creator key upload signs with. There is one Wildshard creator key and
|
|
125
|
+
no per-author creator keys yet: ask the Wildshard team for it, and never commit it. Upload also sends your
|
|
126
|
+
**account key**, which says whose shard it is: the first upload of a slug makes it yours, and nobody else's key can
|
|
127
|
+
upload to it. Make the account once with `wildshard account you@example.com`: it saves the key to
|
|
128
|
+
`~/.config/wildshard/sharddev-key` (only you can read it) and the API never shows it again, so keep that file. An
|
|
129
|
+
email that has an account already is refused (`account-exists`); a lost key needs an operator reset by the
|
|
130
|
+
Wildshard team. In CI, set `WILDSHARD_API_KEY` instead: it wins over the file. `wildshard whoami` says which key
|
|
131
|
+
upload will send and whose it is. Done when `wildshard whoami` prints `key wsk_…` and `account <your email>`.
|
|
132
|
+
6. **Upload,** with a version `X.Y.Z` higher than the last one uploaded (`0.0.1` the first time). Upload reads
|
|
133
|
+
`version` from the repo's `package.json` (`new` writes `0.0.1`; raise it before each upload), or pass `--version`:
|
|
134
|
+
|
|
135
|
+
```sh
|
|
136
|
+
wildshard upload public/shardfiles/my-shard.shardfile --channel staging --version 0.0.1
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Upload checks the shard file as the API will, checks the hero, signs, compresses and sends it, then prints the
|
|
140
|
+
version and what moved. Uploading the same bytes again sends nothing.
|
|
141
|
+
|
|
142
|
+
### Deleting a shard
|
|
143
|
+
|
|
144
|
+
`wildshard delete my-shard` deletes a shard you uploaded, with the same account key: only the key that first uploaded
|
|
145
|
+
a slug can delete it. It makes two calls to the API, with you in between:
|
|
146
|
+
|
|
147
|
+
1. **Start.** It prints what the delete touches: the shard's versions, the channels pointing at it, the grid cells
|
|
148
|
+
placing it, and a plain line saying whether a signed release still plays it. A shard a live release plays can still be deleted: that release
|
|
149
|
+
keeps its copy until its next release.
|
|
150
|
+
2. **Type the slug.** Type `my-shard` and press Enter. Anything else deletes nothing (`delete-not-confirmed`). You
|
|
151
|
+
have 10 minutes; after that the confirmation lapses and you start again (`delete-expired`).
|
|
152
|
+
3. **Finalize.** The shard leaves the catalogue, every channel and the grid at once, and its grid cell is freed
|
|
153
|
+
for the next new shard. Its downloads stop after the daily prune, once no signed release names it.
|
|
154
|
+
|
|
155
|
+
In a script, `wildshard delete my-shard --yes` skips the typing. A deleted slug stays yours: uploading a new version
|
|
156
|
+
of it with your key brings it back, on preview only. Done when the last line starts `deleted my-shard at`.
|
|
157
|
+
|
|
158
|
+
## 2. The shard source
|
|
159
|
+
|
|
160
|
+
A project made by `wildshard new` is a repo with one shard source at `src/`. Inside `src/`:
|
|
161
|
+
|
|
162
|
+
| Path | What it is | Ships in the shard file? |
|
|
163
|
+
|---|---|---|
|
|
164
|
+
| `shard.config.ts` | The build entry: exports `generate` (default) and `buildOptions`. Build runs it | No: its output does |
|
|
165
|
+
| `data/` | JSON rows: identity (`data/identity.json`, the slug), card, layout, creatures, items, quests, text, audio, look, budgets (`data/budgets.json`) | As baked sections, never as code |
|
|
166
|
+
| `generators/` | TypeScript that runs at build time (any Node package, J319) to make terrain, props, maps and sections | No: what they produce does |
|
|
167
|
+
| `behaviour/` | AssemblyScript (`.as`) scripts and `hooks.json`. Build compiles them to Wasm | The compiled Wasm |
|
|
168
|
+
| `assets/` | Source assets, named by their SHA-256 | The ones the shard uses, by hash |
|
|
169
|
+
| `look/` | Recorded entry reads for the build | No |
|
|
170
|
+
| `manifest.json` | The card and discovery fields: name, `card` images, `shardfile` path | The card, as data |
|
|
171
|
+
| `hero.json` | The hero stamp (`wildshard hero` writes it) | No |
|
|
172
|
+
| `proof.json` | Optional: a proof tape `check` plays with `prove` | No |
|
|
173
|
+
| `audio-waiver.json` | Optional: a dated waiver for the audio budget | Into the shard file's admission data |
|
|
174
|
+
|
|
175
|
+
At the repo root, around `src/`:
|
|
176
|
+
|
|
177
|
+
| Path | What it is | Ships in the shard file? |
|
|
178
|
+
|---|---|---|
|
|
179
|
+
| `package.json` | Pins `@wildshard/sdk`, shard-format, engine and `three` exactly, and pnpm 10.34.9 (`packageManager`); its `version` is what upload sends | No |
|
|
180
|
+
| `tsconfig.json`, `.npmrc`, `.gitignore` | TypeScript settings for `src/`; exact versions for `pnpm add`; what git leaves out (build output, `node_modules/`) | No |
|
|
181
|
+
| `README.md`, `GUIDE.md` | This repo's README, and this guide | No |
|
|
182
|
+
| `pnpm-workspace.yaml` | pnpm's install-script allowlist (SA39): a dependency's install script runs only if listed | No |
|
|
183
|
+
| `.claude/skills/wildshard*/SKILL.md` | The `wildshard` skill (SA14): the loop's order for Claude Code, pointing into this guide; and its siblings (SA27): `wildshard-mockup-to-model` (a picture to a model), `wildshard-goldens` (refresh the hero and proof tape), `wildshard-upgrade` (move to a newer sdk). `wildshard update` rewrites them: never edit them | No |
|
|
184
|
+
| `.agents/skills/wildshard*` | Links to the four `.claude/skills/` folders, so Codex lists the same skills | No |
|
|
185
|
+
| `AGENTS.md`, `CLAUDE.md` | For agents: read this guide first; the skills are in `.claude/skills/`. `CLAUDE.md` is `@AGENTS.md`, so Claude Code reads the same file. Yours to change: `update` keeps your edits | No |
|
|
186
|
+
| `public/shardfiles/` | Build output: the built folder and `<slug>.shardfile`. Never edit; never commit | It is the shard file |
|
|
187
|
+
|
|
188
|
+
**Two files to change together.** `src/manifest.json` and `src/data/card.json` hold the same card: `new` writes
|
|
189
|
+
both, build refuses a shard whose two copies differ, and hero capture reads `manifest.json`, so change both together.
|
|
190
|
+
|
|
191
|
+
Blender files (`.blend`), mockups and other working files never ship: keep them in a folder of your own, such as
|
|
192
|
+
`blender/`, and export what the shard needs into `assets/`. A shard never ships runtime TypeScript: everything that
|
|
193
|
+
runs in the game is data, or Wasm compiled from `behaviour/`. `shard.config.ts` and `generators/` run only at build
|
|
194
|
+
time; lint refuses runtime code there (section 6).
|
|
195
|
+
|
|
196
|
+
**Repo layout (J317).** A repo with one shard keeps its shard source at `src/` (`src/shard.config.ts`,
|
|
197
|
+
`src/data/`, ...); a repo with several keeps `src/shards/<slug>/`. Commands take the repo (`.`) and find the shard
|
|
198
|
+
source at `src/`, or at the one `src/shards/<slug>/` a repo holds; in a repo with several, name the shard source
|
|
199
|
+
(`src/shards/<slug>`). The slug is `manifest.json`'s, whatever the repo folder is called. A `src/` source builds
|
|
200
|
+
into the repo's `public/shardfiles/`; a `src/shards/<slug>/` source into its own folder's. SA24 moves the existing
|
|
201
|
+
single-shard repos to `src/`.
|
|
202
|
+
|
|
203
|
+
**The hand-written template (`--template blender`).** shard-format's `blender-template`: no sdk at runtime, no
|
|
204
|
+
three.js, no `shard.config.ts`. Its `src/` is a shard file folder held by hand: `shard.json` (the index),
|
|
205
|
+
`sections/` (the JSON you edit), `blobs/` (baked files, Blender models among them, each named by its SHA-256),
|
|
206
|
+
`mounts/` (what the boot reads first, with its receipt) and `validation.json`. `check` lint skips it (no code); its
|
|
207
|
+
build runs shard-format's `shard-format pack`, which settles every hash and size the sections measure and validates
|
|
208
|
+
the whole folder, then writes the built folder and shard file as any build does. A changed blob is a new file under
|
|
209
|
+
its new hash, with every row that names it changed to match. `package.json` lists only `@wildshard/sdk` (the CLI) and
|
|
210
|
+
shard-format, as dev dependencies; there is no `tsconfig.json`.
|
|
211
|
+
|
|
212
|
+
**What a shard may declare.** The runtime contract lists every section, `client/plan` kind, named file, script rule,
|
|
213
|
+
budget and limit a shard file may carry, and what validation refuses:
|
|
214
|
+
[shard-format `docs/RUNTIME-CONTRACT.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/RUNTIME-CONTRACT.md).
|
|
215
|
+
Read with it [`SHARDFILE.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/SHARDFILE.md) (the
|
|
216
|
+
fields), [`SCRIPT-ABI.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/SCRIPT-ABI.md) (the Wasm
|
|
217
|
+
scripts) and [`PLATFORM-FILE-FAMILIES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/PLATFORM-FILE-FAMILIES.md)
|
|
218
|
+
(the named files). `wildshard schema list` prints the section roots from your installed copy.
|
|
219
|
+
|
|
220
|
+
## 3. Budgets
|
|
221
|
+
|
|
222
|
+
A budget is a limit on what your shard costs a player's phone or desktop: bytes to download, memory, draw calls,
|
|
223
|
+
triangles, script time and audio. Build measures the shard, and the **report card** compares each cost with its limit.
|
|
224
|
+
A cost over a hard limit is a refusal; one over a soft line is a warning. The numbers change with releases, so this
|
|
225
|
+
guide names them and points at what prints them:
|
|
226
|
+
|
|
227
|
+
| Budget | What it limits | Checked by | Where the numbers are |
|
|
228
|
+
|---|---|---|---|
|
|
229
|
+
| Download | Bytes before the shard is playable (critical) and in all (library) | `check` (report), `build`, `validate` | `wildshard check .` prints "N MB download, ~S s to playable"; RUNTIME-CONTRACT §6 |
|
|
230
|
+
| Draws, triangles | Draw calls and triangles in the near and far views | `check` (report) | The report step's refusals: `metric: actual over limit` |
|
|
231
|
+
| Memory | Resident, loading and playing bytes | `check` (report) | Report only for now: printed, not refused (RUNTIME-CONTRACT §6) |
|
|
232
|
+
| Script CPU and fuel | Time and instructions per tick of your Wasm scripts | `check` (report), from a headless run | The report step; SCRIPT-ABI.md |
|
|
233
|
+
| Frame targets | fps and per-system milliseconds per device | The running game reports against them; `check` does not | Your `data/budgets.json` |
|
|
234
|
+
| Server | Tick time, memory, entities, commands per tick | `validate` | `shard.json` `admission.serverBudget`; RUNTIME-CONTRACT §6 |
|
|
235
|
+
| Audio | Your shard's own recordings: green to 6 MB, amber 6 to 10 MB, red over 10 MB (J303) | `build` and `upload` | `check` prints "audio green: ... MB"; shard-format `docs/audio.md` |
|
|
236
|
+
| File limits | Sizes and counts: source bytes, files, ids, text, Wasm modules | `validate`, `upload` | RUNTIME-CONTRACT §7 |
|
|
237
|
+
|
|
238
|
+
`wildshard check . --json` is the one place to read them for your shard: the `report` step's `note` and each refusal's
|
|
239
|
+
`message` carry the measured value and its limit. Shard-format's codes for every budget finding are in
|
|
240
|
+
[`docs/VALIDATION-CODES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/VALIDATION-CODES.md)
|
|
241
|
+
(sections "performance" and "audio"). Section 6 says what to do when one refuses.
|
|
242
|
+
|
|
243
|
+
## 4. What reloads under `dev`
|
|
244
|
+
|
|
245
|
+
`wildshard dev` is **not built yet** for an installed sdk (SA15); this is how it behaves once it runs.
|
|
246
|
+
|
|
247
|
+
- **Every saved file in the shard source rebuilds the whole shard**, about 0.1 s after the last save, and the open page
|
|
248
|
+
reloads itself when the new build is ready. Nothing is patched in place: data, generators, behaviour scripts,
|
|
249
|
+
assets, `shard.config.ts` and `manifest.json` all take the same path.
|
|
250
|
+
- **A failed rebuild keeps the last good build** on the page and prints the refusal in the terminal and the browser
|
|
251
|
+
console. Fix it and save again.
|
|
252
|
+
- **Not watched:** `node_modules/`, `.git/`, `dist/`, `public/` and `.worktrees/`. After `pnpm install` or an sdk
|
|
253
|
+
update, stop `dev` and start it again.
|
|
254
|
+
- **Not made by `dev`:** a shard file to upload. `dev` builds a private copy for the page. Run `wildshard check .`
|
|
255
|
+
for the shard file, and capture the hero again before you upload a changed world.
|
|
256
|
+
|
|
257
|
+
## 5. Channels and the grid
|
|
258
|
+
|
|
259
|
+
**Channels (J301).** Every upload names one:
|
|
260
|
+
|
|
261
|
+
| `--channel` | preview (`preview.wildshard.io`) | staging (`staging.wildshard.io`) | production (`play.wildshard.io`) |
|
|
262
|
+
|---|---|---|---|
|
|
263
|
+
| `staging` | moves to this version | moves to this version | stays |
|
|
264
|
+
| `prod` | moves | moves | moves |
|
|
265
|
+
|
|
266
|
+
There is no default: upload without `--channel` refuses. Upload to staging; once the Wildshard team has placed the
|
|
267
|
+
shard (below), walk it there; then upload the next version with `--channel prod`. The same bytes cannot go to staging
|
|
268
|
+
and then to prod: production needs a new version, and a new version needs a new hero (J306).
|
|
269
|
+
|
|
270
|
+
**The grid.** The world is a grid of cells, one shard per cell, and players walk from cell to cell. Today it is 5×5,
|
|
271
|
+
and only the Wildshard team places a shard on it. An uploaded shard with no cell is recorded on its channels, but no
|
|
272
|
+
player can reach it there yet.
|
|
273
|
+
|
|
274
|
+
**What upload says about the grid (SA32).** After the `committed:` line, upload prints one grid line, then the
|
|
275
|
+
`/slug/<slug>` link on each channel it moved:
|
|
276
|
+
|
|
277
|
+
| Grid line | Means |
|
|
278
|
+
|---|---|
|
|
279
|
+
| `placed at (0,3) on preview, staging` | The shard's cell, and the channels whose grid has it |
|
|
280
|
+
| `grid full, not placed` | Every cell is taken; the upload still counts, and the Wildshard team is told |
|
|
281
|
+
| `not placed (--no-place)` | You passed `--no-place` on the shard's first upload |
|
|
282
|
+
| `grid left as it was (--no-place)` | You passed `--no-place` on a later upload: a cell the shard has stays, and is not added to a new channel |
|
|
283
|
+
| `not placed: the grid step failed; run the same upload again to retry` | The upload counts; the same `wildshard upload` again places it |
|
|
284
|
+
| `no new cell: grid placement is off on the API, or this is not the shard's first upload` | Today's answer: the API does not place yet (below); or the shard had an upload before and no cell |
|
|
285
|
+
|
|
286
|
+
`wildshard upload --no-place` uploads without taking a cell, for a proof upload you will delete. Only a shard's
|
|
287
|
+
first upload can take a cell, so a shard uploaded with `--no-place` never gets one from a later upload. The links
|
|
288
|
+
point at the share page, which is not built yet (below), and each says `(page not built yet)`.
|
|
289
|
+
|
|
290
|
+
**Not built yet:**
|
|
291
|
+
|
|
292
|
+
- **The 7×7 grid that fills itself (J314; SA29 to SA35).** A brand-new slug's first upload will get the nearest free
|
|
293
|
+
cell in the outer ring, and that cell is the slug's for life, on every channel it reaches: a staging upload places
|
|
294
|
+
it on preview and staging, and a later prod upload puts it at the same cell on production. The API side is built
|
|
295
|
+
but switched off until the MMO server and the play page can show a new cell; upload already prints its answer.
|
|
296
|
+
- **The share link (SA36, SA37):** `https://staging.wildshard.io/slug/<slug>` (and the same path on preview and
|
|
297
|
+
production) will show your shard's name and hero with a Play button that spawns you at its cell, and unfurl with
|
|
298
|
+
the hero when pasted into a chat. A shard with no cell shows its card with Play off: "not on the grid yet".
|
|
299
|
+
|
|
300
|
+
**How to share today:** there is no per-shard link yet. Once the Wildshard team has placed your shard, share
|
|
301
|
+
`https://staging.wildshard.io` and its cell; until then, share the hero images and the shard file.
|
|
302
|
+
|
|
303
|
+
## 6. Refusals and their fixes
|
|
304
|
+
|
|
305
|
+
Every refusal prints the refusing code's own words, then one line:
|
|
306
|
+
|
|
307
|
+
```text
|
|
308
|
+
[<rule>] fix: <what to do> (GUIDE.md#<rule's heading>)
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
`wildshard check . --json` carries the same `rule`, `fix` and `guide` on each refusal. The headings below are those
|
|
312
|
+
links, one per rule. The printed `fix` is the short answer; each heading adds why. Shard-format's own refusals also
|
|
313
|
+
carry a stable code, listed in
|
|
314
|
+
[`docs/VALIDATION-CODES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/VALIDATION-CODES.md);
|
|
315
|
+
the rule is chosen by that code, and each heading below that one names lists its codes.
|
|
316
|
+
|
|
317
|
+
### Any command
|
|
318
|
+
|
|
319
|
+
#### usage
|
|
320
|
+
|
|
321
|
+
A verb got arguments or flags it does not take. `wildshard <verb> --help` prints what it takes.
|
|
322
|
+
|
|
323
|
+
### New
|
|
324
|
+
|
|
325
|
+
#### new-target
|
|
326
|
+
|
|
327
|
+
`new` needs a folder that does not exist yet and a kebab-case slug (`my-shard`, not `My Shard`). It never writes into
|
|
328
|
+
an existing folder.
|
|
329
|
+
|
|
330
|
+
#### new-template
|
|
331
|
+
|
|
332
|
+
`--template` names `sdk` (the reference world, the default) or `blender` (the hand-written Blender template). Any
|
|
333
|
+
other name refuses before `new` writes anything. Leave the flag out or pass `--template sdk` or `--template blender`.
|
|
334
|
+
|
|
335
|
+
#### new-refused
|
|
336
|
+
|
|
337
|
+
`new` could not copy the reference world shipped with the sdk. Reinstall the sdk.
|
|
338
|
+
|
|
339
|
+
### Update
|
|
340
|
+
|
|
341
|
+
#### update-target
|
|
342
|
+
|
|
343
|
+
`update` works on a shard repo: a folder whose `package.json` lists `@wildshard/sdk`, as `new` writes it. Run it in
|
|
344
|
+
that folder, or name it: `wildshard update my-shard`.
|
|
345
|
+
|
|
346
|
+
#### update-pins
|
|
347
|
+
|
|
348
|
+
`wildshard update --pins` (SA18) is not built yet. Move the pins by hand as the `wildshard-upgrade` skill says, then
|
|
349
|
+
run `wildshard update` with no flag.
|
|
350
|
+
|
|
351
|
+
#### update-refused
|
|
352
|
+
|
|
353
|
+
`update` could not copy this guide or a skill from the installed sdk. Reinstall the sdk (`pnpm install`).
|
|
354
|
+
|
|
355
|
+
### Build
|
|
356
|
+
|
|
357
|
+
#### source-file-missing
|
|
358
|
+
|
|
359
|
+
A path the command was given, or a file the shard source names, is not there. Check the path in the message.
|
|
360
|
+
|
|
361
|
+
#### source-import-missing
|
|
362
|
+
|
|
363
|
+
An import in `shard.config.ts`, `generators/` or `data/` names a file or package that is not there. Fix the path, or
|
|
364
|
+
add the package to `package.json` and install.
|
|
365
|
+
|
|
366
|
+
#### json-syntax
|
|
367
|
+
|
|
368
|
+
A JSON file in the shard source does not parse. The message gives the line and column.
|
|
369
|
+
|
|
370
|
+
#### source-syntax
|
|
371
|
+
|
|
372
|
+
A TypeScript or AssemblyScript file does not parse. The message gives the file and line.
|
|
373
|
+
|
|
374
|
+
#### config-default-export
|
|
375
|
+
|
|
376
|
+
`shard.config.ts` must default-export its `generate` function, as `new` wrote it.
|
|
377
|
+
|
|
378
|
+
#### config-file-access
|
|
379
|
+
|
|
380
|
+
Code that `shard.config.ts` imports read a file with `node:fs`. Read files through the build context (`ctx.cached`),
|
|
381
|
+
so build knows the input and can cache it.
|
|
382
|
+
|
|
383
|
+
#### project-folder-slug
|
|
384
|
+
|
|
385
|
+
The shard source's folder name and its slug (`data/identity.json`) differ. Rename one to match the other.
|
|
386
|
+
|
|
387
|
+
#### source-schema
|
|
388
|
+
|
|
389
|
+
A field in your data does not have the shape the shard file needs. The message gives the path;
|
|
390
|
+
`wildshard schema shardfile <pointer>` prints the expected shape.
|
|
391
|
+
|
|
392
|
+
#### build-refused
|
|
393
|
+
|
|
394
|
+
Build stopped for a reason no rule above names. Read the message: it names the file, field or generator. Fix it and
|
|
395
|
+
run `wildshard check .` again.
|
|
396
|
+
|
|
397
|
+
### Validate
|
|
398
|
+
|
|
399
|
+
#### validate-refused
|
|
400
|
+
|
|
401
|
+
Shard-format's checks refused the built shard. The message names the check; RUNTIME-CONTRACT §8 lists what is refused.
|
|
402
|
+
If a fresh, unedited build still fails, report it with the message.
|
|
403
|
+
|
|
404
|
+
### Prove
|
|
405
|
+
|
|
406
|
+
#### proof-tape-invalid
|
|
407
|
+
|
|
408
|
+
`proof.json` does not have the proof tape's shape. Fix it where the message says.
|
|
409
|
+
|
|
410
|
+
#### proof-failed
|
|
411
|
+
|
|
412
|
+
The tape played, but a step it expected did not happen. Fix the data, or the tape step.
|
|
413
|
+
|
|
414
|
+
### Budgets
|
|
415
|
+
|
|
416
|
+
Each of these is the report card naming a budget over its limit (section 3). The message gives the measured value and
|
|
417
|
+
the limit.
|
|
418
|
+
|
|
419
|
+
#### budget-unmeasured
|
|
420
|
+
|
|
421
|
+
A cost could not be measured: too few headless ticks for scripts, or native gameplay that needs a browser run. Codes
|
|
422
|
+
`perf-native-view-unmeasured`, `perf-native-resident-unmeasured`, `perf-script-sample-invalid`,
|
|
423
|
+
`perf-script-samples-missing`.
|
|
424
|
+
|
|
425
|
+
#### budget-download
|
|
426
|
+
|
|
427
|
+
Too many bytes to download, before play (critical) or in all (library). Shrink or drop assets, or load them later.
|
|
428
|
+
Codes `perf-library-download-budget`, `perf-critical-download-budget`, `perf-library-download`,
|
|
429
|
+
`perf-critical-download`, `perf-tile-download`, `perf-far-download`.
|
|
430
|
+
|
|
431
|
+
#### budget-draws
|
|
432
|
+
|
|
433
|
+
Too many draw calls in a view. Merge meshes that share a material, or show fewer objects from that view. Codes
|
|
434
|
+
`perf-tile-draws`, `perf-far-draws`.
|
|
435
|
+
|
|
436
|
+
#### budget-triangles
|
|
437
|
+
|
|
438
|
+
Too many triangles in a view. Use lower-detail meshes or fewer props there. Codes `perf-tile-triangles`,
|
|
439
|
+
`perf-far-triangles`.
|
|
440
|
+
|
|
441
|
+
#### budget-memory
|
|
442
|
+
|
|
443
|
+
A memory total is over its line. Smaller or fewer textures and meshes. Memory reports only, for now. Codes
|
|
444
|
+
`perf-memory-target`, `perf-playing-memory`, `perf-loading-memory`.
|
|
445
|
+
|
|
446
|
+
#### budget-script-cpu
|
|
447
|
+
|
|
448
|
+
Behaviour scripts take too long per tick. Spread work over ticks, or run it on events. Code `perf-script-cpu`.
|
|
449
|
+
|
|
450
|
+
#### budget-script-fuel
|
|
451
|
+
|
|
452
|
+
Behaviour scripts run too many instructions per tick. Shorten the hottest loops. Code `perf-script-fuel`.
|
|
453
|
+
|
|
454
|
+
#### budget-over
|
|
455
|
+
|
|
456
|
+
A budget not named above is over its limit. The message names it; `wildshard check . --json` lists each.
|
|
457
|
+
|
|
458
|
+
#### budget-refused
|
|
459
|
+
|
|
460
|
+
Build or validate refused the whole report card. Run `wildshard check .`: its report step names each budget over.
|
|
461
|
+
Codes `declared-costs`, `performance-targets` (shard-format checking the costs the shard file declares).
|
|
462
|
+
|
|
463
|
+
### The shard file and the hero
|
|
464
|
+
|
|
465
|
+
#### hero-stale
|
|
466
|
+
|
|
467
|
+
The shard's content changed after its hero was captured, or the card names images `hero.json` has no stamp for. The
|
|
468
|
+
hero must show the current world: capture it again (`wildshard hero . --base <url>`). Only if the images already show
|
|
469
|
+
the current world, `wildshard hero . --stamp-existing`.
|
|
470
|
+
|
|
471
|
+
#### hero-not-in-product
|
|
472
|
+
|
|
473
|
+
The shard file does not carry the captured hero: it was built before the capture. Run `wildshard check .`, then
|
|
474
|
+
prepare again ("Uploading", steps 3 and 4).
|
|
475
|
+
|
|
476
|
+
#### hero-unchanged
|
|
477
|
+
|
|
478
|
+
Upload only: this new version's hero is the same as the previous version's (J306: a new version needs a new hero).
|
|
479
|
+
Capture a new hero, build, prepare and upload again.
|
|
480
|
+
|
|
481
|
+
#### audio-refused
|
|
482
|
+
|
|
483
|
+
The audio rules found a red problem: a recording that will not play, runs too long, or a shard over 10 MB of its own
|
|
484
|
+
audio. Fix each red finding, or add a dated waiver in `audio-waiver.json`. Shard-format `docs/audio.md` explains each.
|
|
485
|
+
Code `audio-refused`. Build prints every finding with one of the rules below under it; only upload refuses a red one.
|
|
486
|
+
|
|
487
|
+
#### audio-unreadable
|
|
488
|
+
|
|
489
|
+
Red. The recording does not read as AAC-LC at 48 kHz, mono or stereo. Export it again in that form. Code
|
|
490
|
+
`audio-unreadable`.
|
|
491
|
+
|
|
492
|
+
#### audio-container
|
|
493
|
+
|
|
494
|
+
Red. The recording's bytes are FLAC, AIFF, Ogg, MP3, WebM, CAF or no container the game knows; it still counts toward
|
|
495
|
+
the audio budget. Export it again as AAC (in an mp4 file) or as WAV. Code `audio-container`.
|
|
496
|
+
|
|
497
|
+
#### audio-encoding
|
|
498
|
+
|
|
499
|
+
Amber. The recording plays, but it is PCM WAV, AAC at a sample rate other than 48 kHz, or AAC outside the strict
|
|
500
|
+
playback index. Encode it as AAC-LC at 48 kHz. Codes `audio-wav`, `audio-sample-rate`, `audio-strict-index`.
|
|
501
|
+
|
|
502
|
+
#### audio-duration
|
|
503
|
+
|
|
504
|
+
Red. The recording runs longer than the maximum the message gives. Cut it, or split it in two. Code `audio-duration`.
|
|
505
|
+
|
|
506
|
+
#### audio-bitrate
|
|
507
|
+
|
|
508
|
+
Amber. The recording's bitrate is over the cap for its role (music or sound effect) and channels. Encode it lower.
|
|
509
|
+
Code `audio-bitrate`.
|
|
510
|
+
|
|
511
|
+
#### audio-budget
|
|
512
|
+
|
|
513
|
+
The shard's own audio is over the amber line (amber), over the red line (red), or over the red line with a dated
|
|
514
|
+
waiver that holds (amber). Cut, shorten or re-encode recordings, or add a waiver in `audio-waiver.json`. Codes
|
|
515
|
+
`audio-budget-amber`, `audio-budget-red`, `audio-budget-waived`.
|
|
516
|
+
|
|
517
|
+
#### audio-waiver
|
|
518
|
+
|
|
519
|
+
Amber. `audio-waiver.json` names another shard, has expired, or covers fewer bytes than the shard holds, so it does
|
|
520
|
+
not hold; the budget finding after it says what that leaves. Code `audio-waiver-invalid`.
|
|
521
|
+
|
|
522
|
+
#### shardfile-draft
|
|
523
|
+
|
|
524
|
+
A warning from `build` and `check`, a refusal from `upload`: the shard file is a draft (`sdk: "0.2"`). Prepare it
|
|
525
|
+
first ("Uploading", step 1).
|
|
526
|
+
|
|
527
|
+
#### shardfile-link
|
|
528
|
+
|
|
529
|
+
The built folder holds a symbolic link; a shard file holds only real files. Replace the link, then check and prepare
|
|
530
|
+
again ("Uploading", steps 3 and 4).
|
|
531
|
+
|
|
532
|
+
#### shardfile-folder-missing
|
|
533
|
+
|
|
534
|
+
There is no built folder to write a shard file from. Run `wildshard check .` (or `wildshard build .`) first.
|
|
535
|
+
|
|
536
|
+
#### shardfile-invalid
|
|
537
|
+
|
|
538
|
+
The shard file breaks a format check: it is not a tarball shard-format can read. Upload the shard file `prepare` and
|
|
539
|
+
`build <folder>` wrote, unedited. Code `archive-invalid`.
|
|
540
|
+
|
|
541
|
+
#### shardfile-index
|
|
542
|
+
|
|
543
|
+
`shard.json` is missing, too large, not canonical JSON, or does not fit the index schema. Build again so it is written
|
|
544
|
+
for you; a hand-written shard file's `shard.json` must parse and fit. Code `index-invalid`.
|
|
545
|
+
|
|
546
|
+
#### shardfile-files
|
|
547
|
+
|
|
548
|
+
The files in the folder differ from the ones `shard.json` lists: one is missing, changed or a link, one is not listed,
|
|
549
|
+
a pack lacks a member, or the sections differ from the source hash. Something edited the built folder: build again.
|
|
550
|
+
Codes `file-mismatch`, `unlisted-file`, `source-hash`, `pack-invalid`.
|
|
551
|
+
|
|
552
|
+
#### shardfile-section
|
|
553
|
+
|
|
554
|
+
A section, or the whole shard file the sections make, does not fit its schema. The message gives the path;
|
|
555
|
+
`wildshard schema shardfile <pointer>` prints the expected shape. Codes `section-invalid`, `shard-schema`.
|
|
556
|
+
|
|
557
|
+
#### shardfile-assets
|
|
558
|
+
|
|
559
|
+
An asset's bytes do not match what the shard file declares (its kind, extension, schema, size or costs), or fail
|
|
560
|
+
the asset checks, or a mount or runtime file is wrong. Export the named asset again and build. Codes `blob-invalid`,
|
|
561
|
+
`server-file-invalid`, `ktx2-costs`, `asset-admission`, `cook-invalid`, `runtime-files`.
|
|
562
|
+
|
|
563
|
+
#### shardfile-scripts
|
|
564
|
+
|
|
565
|
+
A behaviour script runs on a side (client or server) its declaration does not allow, or the script rows are
|
|
566
|
+
invalid. Fix the declaration or move the script, then build again. Codes `script-side`, `script-admission`.
|
|
567
|
+
|
|
568
|
+
#### shardfile-targets
|
|
569
|
+
|
|
570
|
+
The world targets name an item or quest the shard does not declare. Declare it, or take it out. Code `world-targets`.
|
|
571
|
+
|
|
572
|
+
#### shardfile-stream
|
|
573
|
+
|
|
574
|
+
Upload's streaming check refused: a file, pack or the placed assets are over the streaming cap, or the stored file
|
|
575
|
+
changed while it was read. Shrink what the message names; if it changed mid-read, upload again. Codes `stream-cap`,
|
|
576
|
+
`stream-miss`, `stream-changed`.
|
|
577
|
+
|
|
578
|
+
#### shardfile-refused
|
|
579
|
+
|
|
580
|
+
Writing or checking the shard file failed for another reason. Check and prepare again ("Uploading", steps 3 and 4).
|
|
581
|
+
|
|
582
|
+
### Upload
|
|
583
|
+
|
|
584
|
+
Upload checks all of these before a byte is sent.
|
|
585
|
+
|
|
586
|
+
#### upload-shardfile-missing
|
|
587
|
+
|
|
588
|
+
The path is not a shard file. Pass the one build wrote: `public/shardfiles/<slug>.shardfile`.
|
|
589
|
+
|
|
590
|
+
#### upload-channel
|
|
591
|
+
|
|
592
|
+
No `--channel`, or one that is not `staging` or `prod` (section 5).
|
|
593
|
+
|
|
594
|
+
#### upload-credentials
|
|
595
|
+
|
|
596
|
+
`WILDSHARD_API_URL` (or `--server`) or `WILDSHARD_CREATOR_PRIVATE_KEY` is not set ("Uploading", step 5).
|
|
597
|
+
|
|
598
|
+
#### upload-level
|
|
599
|
+
|
|
600
|
+
`--level` is the compression level, 0 to 11. Leave it out for the default.
|
|
601
|
+
|
|
602
|
+
#### upload-version
|
|
603
|
+
|
|
604
|
+
No version: set `version` (X.Y.Z) in `package.json`, or pass `--version X.Y.Z`, higher than the last one uploaded.
|
|
605
|
+
|
|
606
|
+
#### upload-commit
|
|
607
|
+
|
|
608
|
+
The shard source is not in a git checkout, or `--commit` is not a full 40-character sha. Upload names the commit
|
|
609
|
+
its bytes came from.
|
|
610
|
+
|
|
611
|
+
#### upload-uncommitted
|
|
612
|
+
|
|
613
|
+
Tracked files have uncommitted changes. Commit, then check and prepare again before you upload ("Uploading").
|
|
614
|
+
|
|
615
|
+
#### upload-sdk-missing
|
|
616
|
+
|
|
617
|
+
Upload could not find the sdk, engine or shard-format version to send. Install the project's packages.
|
|
618
|
+
|
|
619
|
+
#### upload-refused
|
|
620
|
+
|
|
621
|
+
The API refused, or a check no rule above names. The message says what it wants: a format refusal means check and
|
|
622
|
+
prepare again; a server refusal (409 or 422) names the field, the version or the hero.
|
|
623
|
+
|
|
624
|
+
### Account
|
|
625
|
+
|
|
626
|
+
The account key upload sends ("Uploading", step 5), `wildshard account` and `wildshard whoami`.
|
|
627
|
+
|
|
628
|
+
#### account-key-missing
|
|
629
|
+
|
|
630
|
+
Upload found no account key: `WILDSHARD_API_KEY` is unset and `~/.config/wildshard/sharddev-key` is not there. It
|
|
631
|
+
refuses before anything is sent, because the API refuses an upload with no key. Run `wildshard account <email>` once,
|
|
632
|
+
or set `WILDSHARD_API_KEY`.
|
|
633
|
+
|
|
634
|
+
#### account-exists
|
|
635
|
+
|
|
636
|
+
That email has an account already, and the API shows a key only once, when the account is made. Use the key you
|
|
637
|
+
saved for it. A lost key stays lost until the Wildshard team resets it.
|
|
638
|
+
|
|
639
|
+
#### account-key-file
|
|
640
|
+
|
|
641
|
+
`~/.config/wildshard/sharddev-key` already holds a key, and `account` never overwrites one by accident: you would lose
|
|
642
|
+
the key to an account you made. Keep it, or pass `--force` to replace the file; the old key keeps working.
|
|
643
|
+
|
|
644
|
+
#### account-refused
|
|
645
|
+
|
|
646
|
+
The API refused the account for another reason: a malformed email is 400, and more than five tries a minute is 429
|
|
647
|
+
(wait a minute).
|
|
648
|
+
|
|
649
|
+
### Delete
|
|
650
|
+
|
|
651
|
+
`wildshard delete <slug>` ("Deleting a shard"). No account key refuses before anything is sent
|
|
652
|
+
(`account-key-missing`, above).
|
|
653
|
+
|
|
654
|
+
#### delete-not-confirmed
|
|
655
|
+
|
|
656
|
+
You typed something other than the slug, or nothing, so the delete was not finalized and nothing changed. Run it
|
|
657
|
+
again and type the slug exactly; in a script, pass `--yes`.
|
|
658
|
+
|
|
659
|
+
#### delete-expired
|
|
660
|
+
|
|
661
|
+
The confirmation from the start call was spent, or its 10 minutes passed, so finalize changed nothing. Run
|
|
662
|
+
`wildshard delete <slug>` again and type the slug within 10 minutes.
|
|
663
|
+
|
|
664
|
+
#### delete-not-owner
|
|
665
|
+
|
|
666
|
+
The key you sent does not own this shard: only the account whose key first uploaded a slug can delete it (the
|
|
667
|
+
Wildshard team can delete any shard). `wildshard whoami` shows which key you send. A 401 means the API does not know
|
|
668
|
+
the key at all.
|
|
669
|
+
|
|
670
|
+
#### delete-unknown
|
|
671
|
+
|
|
672
|
+
The API has no shard by that slug (404), or the slug is not a valid one (400). Check its spelling against the
|
|
673
|
+
catalogue.
|
|
674
|
+
|
|
675
|
+
#### delete-refused
|
|
676
|
+
|
|
677
|
+
The API refused for another reason, or `--server` is not https (the key goes only to https or localhost). The
|
|
678
|
+
message says which.
|
|
679
|
+
|
|
680
|
+
### Lint
|
|
681
|
+
|
|
682
|
+
`check` lints the shard source with the sdk's rules. Each wildshard lint rule keeps a shard to data and build-time
|
|
683
|
+
code; its printed fix says what to change.
|
|
684
|
+
|
|
685
|
+
#### lint-not-run
|
|
686
|
+
|
|
687
|
+
The linter that ships with the sdk did not run. Reinstall the sdk.
|
|
688
|
+
|
|
689
|
+
#### lint-refused
|
|
690
|
+
|
|
691
|
+
A lint finding with no rule of its own. Fix what it names at the file and line shown.
|
|
692
|
+
|
|
693
|
+
#### lint-rules
|
|
694
|
+
|
|
695
|
+
A lint rule that is not Wildshard's own (oxlint's built-in rules). Its own help line is printed as the fix.
|
|
696
|
+
|
|
697
|
+
#### lint-generator-imports
|
|
698
|
+
|
|
699
|
+
An import the rule denies. In `generators/` any npm package, valibot, shard-format and `node:*` are fine (J319); the
|
|
700
|
+
rule denies engine, sdk paths outside its exports, another shard's source and a second copy of `three`. In `data/` and
|
|
701
|
+
`shard.config.ts` only `three`, valibot, shard-format, the sdk and Node built-ins are allowed.
|
|
702
|
+
|
|
703
|
+
#### lint-engine-internal
|
|
704
|
+
|
|
705
|
+
Shard code imports a game-only engine export; use the sdk's shard-facing one.
|
|
706
|
+
|
|
707
|
+
#### lint-engine-sides
|
|
708
|
+
|
|
709
|
+
Client and server code are mixed; import the shared module instead.
|
|
710
|
+
|
|
711
|
+
#### lint-engine-words
|
|
712
|
+
|
|
713
|
+
Shard and game names belong in content data, not in engine code.
|
|
714
|
+
|
|
715
|
+
#### lint-exec-max-buffer
|
|
716
|
+
|
|
717
|
+
An exec call that captures output needs an explicit `maxBuffer`.
|
|
718
|
+
|
|
719
|
+
#### lint-layer
|
|
720
|
+
|
|
721
|
+
An import reaches upward or into another shard; import through the public index.
|
|
722
|
+
|
|
723
|
+
#### lint-no-active-chunk
|
|
724
|
+
|
|
725
|
+
Read current content through the game layer, not the active chunk.
|
|
726
|
+
|
|
727
|
+
#### lint-no-active-singleton
|
|
728
|
+
|
|
729
|
+
Take the service from your context, not a global singleton.
|
|
730
|
+
|
|
731
|
+
#### lint-no-authored-html
|
|
732
|
+
|
|
733
|
+
Set text with `textContent`, never HTML.
|
|
734
|
+
|
|
735
|
+
#### lint-no-base64
|
|
736
|
+
|
|
737
|
+
Binary content stays binary: ship bytes as an asset, never base64 text.
|
|
738
|
+
|
|
739
|
+
#### lint-no-build-time-import
|
|
740
|
+
|
|
741
|
+
Runtime code imports build-time code. Move the shared part into a runtime module.
|
|
742
|
+
|
|
743
|
+
#### lint-no-client-plan-reflection
|
|
744
|
+
|
|
745
|
+
Pass data to a client feature; never reflect into shard TypeScript.
|
|
746
|
+
|
|
747
|
+
#### lint-no-generated-import
|
|
748
|
+
|
|
749
|
+
Do not import a generated file; call the function that makes it, or read the built folder.
|
|
750
|
+
|
|
751
|
+
#### lint-no-generated-json-import
|
|
752
|
+
|
|
753
|
+
Read generated JSON as data at build time, not through an import.
|
|
754
|
+
|
|
755
|
+
#### lint-no-global-listener-patch
|
|
756
|
+
|
|
757
|
+
Register listeners through your scope, not on globals.
|
|
758
|
+
|
|
759
|
+
#### lint-no-hook-chain
|
|
760
|
+
|
|
761
|
+
Subscribe to the typed event instead of chaining hooks.
|
|
762
|
+
|
|
763
|
+
#### lint-no-inline-ui-string
|
|
764
|
+
|
|
765
|
+
Player-facing text goes in the string table, `data/text.json`.
|
|
766
|
+
|
|
767
|
+
#### lint-no-level-identity
|
|
768
|
+
|
|
769
|
+
Put level and style choices in data instead of branching on the shard's identity.
|
|
770
|
+
|
|
771
|
+
#### lint-no-module-mock
|
|
772
|
+
|
|
773
|
+
Test through a seam (pass the dependency in), not a module mock.
|
|
774
|
+
|
|
775
|
+
#### lint-no-production-test-import
|
|
776
|
+
|
|
777
|
+
Production code imports a test module. Move what it needs out of the test.
|
|
778
|
+
|
|
779
|
+
#### lint-no-raw-animation-mixer
|
|
780
|
+
|
|
781
|
+
Use the engine's animation API, not a raw three.js mixer.
|
|
782
|
+
|
|
783
|
+
#### lint-no-raw-hud
|
|
784
|
+
|
|
785
|
+
Mount HUD through the numbered HUD slots your scope owns.
|
|
786
|
+
|
|
787
|
+
#### lint-no-raw-input
|
|
788
|
+
|
|
789
|
+
Read input through the input service, not DOM listeners.
|
|
790
|
+
|
|
791
|
+
#### lint-no-raw-random-time
|
|
792
|
+
|
|
793
|
+
Use the engine's seeded random and clock, never `Math.random` or `Date`: the game must replay the same way.
|
|
794
|
+
|
|
795
|
+
#### lint-no-raw-save
|
|
796
|
+
|
|
797
|
+
Save through the saves service, not `localStorage`.
|
|
798
|
+
|
|
799
|
+
#### lint-no-raw-shader-patch
|
|
800
|
+
|
|
801
|
+
Patch shaders through the shader registry.
|
|
802
|
+
|
|
803
|
+
#### lint-no-reexport
|
|
804
|
+
|
|
805
|
+
Import a name from the module that defines it; do not re-export it.
|
|
806
|
+
|
|
807
|
+
#### lint-no-renderer-type
|
|
808
|
+
|
|
809
|
+
Renderer types stay inside rendering code; pass plain data out.
|
|
810
|
+
|
|
811
|
+
#### lint-no-runtime-generator
|
|
812
|
+
|
|
813
|
+
Generators run at build time only: import them from `shard.config.ts`, bakers and other generators.
|
|
814
|
+
|
|
815
|
+
#### lint-no-runtime-in-build
|
|
816
|
+
|
|
817
|
+
Build code imports runtime code. Share a plain data module instead.
|
|
818
|
+
|
|
819
|
+
#### lint-no-shard-branch
|
|
820
|
+
|
|
821
|
+
A shard-specific choice belongs in the shard's data, not a branch on its name.
|
|
822
|
+
|
|
823
|
+
#### lint-no-shard-host-callback
|
|
824
|
+
|
|
825
|
+
Give host APIs data, not TypeScript callbacks: a shard file carries no code engine runs.
|
|
826
|
+
|
|
827
|
+
#### lint-no-shard-runtime
|
|
828
|
+
|
|
829
|
+
The shard source holds authoring and declarations; gameplay goes in `behaviour/` scripts.
|
|
830
|
+
|
|
831
|
+
#### lint-no-url-switch
|
|
832
|
+
|
|
833
|
+
No URL query switches; read settings from the shard's data.
|
|
834
|
+
|
|
835
|
+
#### lint-public-index
|
|
836
|
+
|
|
837
|
+
Import a package by its public export, not a file path inside it.
|
|
838
|
+
|
|
839
|
+
#### lint-runtime-commons
|
|
840
|
+
|
|
841
|
+
Runtime code imports build-time commons; use the runtime export.
|
|
842
|
+
|
|
843
|
+
#### lint-runtime-performance
|
|
844
|
+
|
|
845
|
+
Runtime code must bound its work: no per-frame allocation, raw rendering, DOM, timers or fetch.
|
|
846
|
+
|
|
847
|
+
#### lint-runtime-standalone
|
|
848
|
+
|
|
849
|
+
Runtime code imports only the runtime surface.
|
|
850
|
+
|
|
851
|
+
#### lint-sdk-no-facade
|
|
852
|
+
|
|
853
|
+
Import the sdk's own export; do not alias a game or engine binding.
|
|
854
|
+
|
|
855
|
+
#### lint-shard-engine-imports
|
|
856
|
+
|
|
857
|
+
Shard source imports `@wildshard/sdk`, never engine internals (J158).
|
|
858
|
+
|
|
859
|
+
#### lint-shard-game-imports
|
|
860
|
+
|
|
861
|
+
Shard source imports `@wildshard/sdk`, never the game.
|
|
862
|
+
|
|
863
|
+
#### lint-shard-game-plugins
|
|
864
|
+
|
|
865
|
+
Import only the game plugin exports that define your runtime.
|
|
866
|
+
|
|
867
|
+
#### lint-shard-names
|
|
868
|
+
|
|
869
|
+
Name no other shard outside its own folder.
|
|
870
|
+
|
|
871
|
+
#### lint-shard-sandbox
|
|
872
|
+
|
|
873
|
+
Services, globals, settings and assets stay inside the shard's context.
|
|
874
|
+
|
|
875
|
+
#### lint-shard-services
|
|
876
|
+
|
|
877
|
+
Get engine services from `ShardContext`.
|
|
878
|
+
|
|
879
|
+
#### lint-sim-no-render
|
|
880
|
+
|
|
881
|
+
Code the headless simulation imports must not render.
|
|
882
|
+
|
|
883
|
+
## 7. `wildshard update`
|
|
884
|
+
|
|
885
|
+
`wildshard update` (or `wildshard update <dir>`) rewrites this guide and the four `wildshard` skills in
|
|
886
|
+
`.claude/skills/` from the installed sdk, and prints each file it wrote. Run it after you move to a newer sdk; the
|
|
887
|
+
`wildshard-upgrade` skill walks the whole move. It touches nothing else: your shard source, `package.json`, README and
|
|
888
|
+
every other file stay as they are. It adds the `.agents/skills/` links, `AGENTS.md` and `CLAUDE.md` only if one is
|
|
889
|
+
missing, and it leaves an `AGENTS.md` or `CLAUDE.md` you changed and says so (`left AGENTS.md: you changed it`). So
|
|
890
|
+
keep your own notes for agents in `AGENTS.md`, never in this guide or a skill: `update` rewrites those. Done when it
|
|
891
|
+
prints `already up to date` or the files it wrote, and `git status` shows only `GUIDE.md`, `.claude/skills/` and any
|
|
892
|
+
agent file it added.
|
|
893
|
+
|
|
894
|
+
`wildshard update --pins` (SA18) is not built yet: it will also move the sdk, shard-format and `three` versions,
|
|
895
|
+
install, apply the release's code changes and run the build.
|