Document reusable HTML template prefabs and the closed entity-reference grammar - #1167
Merged
Conversation
…nce grammar Adds a Web Components guide for cloning native <template> elements as scene prefabs (issue #1166): the single entity-fronting root convention, the clone / capture / configure / append / await / remove sequence, clone-local names vs document-global ids, per-element readiness, and teardown racing initialization - with a runnable crate-spawning example. Also updates the Attributes page and every affected tag/script page to the entity-reference grammar shipped by web-components#433: a bare value is an entity name resolved nearest-first, only #-prefixed values are (document-wide) selectors, and unresolved legacy bare ids warn with the escaped #id spelling. Fixes #1166 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A pc-node only binds beneath its owning pc-model - anywhere else it warns, never binds, and ready() never settles - and removing it reverts the model-authored node rather than destroying it. Present pc-entity and pc-model as the general prefab roots and call pc-node out as the specialized case, en + ja. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Sep 4, 2026
willeastcott
added a commit
that referenced
this pull request
Sep 4, 2026
…LOD (#1177) * docs: track Web Components 0.22.0 - engine 2.22.0 and budgeted splat LOD 0.20.0 and 0.21.0 were already documented (#1167, #1172, #1174, #1175), so this is the 0.21.0 -> 0.22.0 delta, which is one library commit with user-facing effect: the update for Engine 2.22 compatibility (#458). The engine pin moves from 2.21.4 to 2.22.0. That is ENGINE_VERSION in LiveExample/shell.js and the camera-controls helper URL inside the seven fences that load it, in both locales - fourteen files, one URL form before and after, confirmed served by jsDelivr before anything was edited. PWC_VERSION moves to 0.22.0. Gaussian splat LOD is no longer a per-splat distance schedule. Engine 2.22 chooses LOD levels globally against a scene-wide splat budget, so pc-gsplat loses lod-base-distance and lod-multiplier and gains lod-falloff (an exponent, 0 to 8, default 1), while pc-scene gains gsplat-splat-budget (default 1,000,000) and gsplat-lod-mode (error or distance). The two pages could each just grow or lose table rows, but a reader would then have to work out for themselves why the knob that sets the budget lives on the scene and the knob that spends it lives on the splat, so pc-gsplat gains a Level of Detail section that lays the split out in one table with a combined example. Two facts in it come from the engine's GSplatParams documentation rather than the library's: a budget larger than the scene resolves every node at its finest level, and there is no way to switch budgeted selection off - a non-positive budget warns and keeps the default rather than lifting the cap. The section also says what none of this touches: a plain .ply, .sog or .splat with no LOD levels always renders in full. The removed attributes appeared only in the two pc-gsplat table rows; no fence used them. The Japanese pages mirror every change, and the pc-scene rows in both locales cross-link the new section. Verification, all at the new pins: - The gsplat, scene, collision, rigid-body and screen tables were audited against observedAttributes and the elements' cached defaults by script, not by eye; names and defaults match. - 31/31 tags resolve against the library's golden list; 31 fences are byte-identical en/ja apart from translated comments, with a single engine URL form; lint is clean over 1344 files; the build is clean for en and ja, so the new level-of-detail anchor resolves in both. - All 31 live examples boot at engine 2.22.0 / library 0.22.0. The one report was the documented cold-start artifact - the first page a fresh Chrome loads loses its jsDelivr fetch at any pin - and the same URL passed on the thirteen other pages that use it. - Rendering was checked across the engine bump, because a console-clean example can still look wrong: pc-render and pc-light are pixel- identical at 2.21.4 and 2.22.0, pc-model is acne-free at both, and pc-gsplat - the page whose engine internals actually changed - draws 183,913 non-clear pixels (23.5% of the frame) at both pins with an empty console. The scene's gsplat parameters were also observed wired through with the attributes absent: lodMode error and splatBudget 1,000,000 at 2.22.0, against a bare splatBudget of 0 at 2.21.4. Worth recording: the first splat probe came back blank at both pins and looked like a regression. It was the cold-start fetch failure taking the local .sog down along with the helper script, since a single-page probe in a fresh Chrome is always the first page. A warm-up load before the measured one fixed the probe; nothing in the release needed fixing. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: name the splat LOD metadata file correctly The Level of Detail section said a streamed splat is exported "alongside a .lod-meta.json". Both halves were wrong. The engine's octree parser matches on the basename being exactly lod-meta.json - a plain filename, not a dotfile and not an extension - and the Splat Streaming example points its pc-asset src straight at .../v1/lod-meta.json. So the file is what the asset IS, not a sidecar beside it; the splat data then streams in on demand. The leading dot came from the library's JSDoc, which spells it .lod-meta.json in the same style as .ply and .sog, and was copied without checking. Corrected in both locales. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1166.
New guide: Reusable Scenes with Templates
Adds
user-manual/web-components/templates(en + ja), linked from the sidebar and the section index. It documents the pattern the AR Wiener Storm, UI Layout, Scroll View and Physics Cluster examples rely on:pc-*markup inside a native<template>stays inert until a clone is appended;#references, assets and materials stay document-global — and whyids don't belong inside repeated content;requestAnimationFrame;ready()never settles, so race the await against a teardown signal.The guide's runnable live example (crate spawner: spawn, impulse-after-ready, click-to-remove, clear) was verified headlessly over CDP against the pinned versions (engine 2.21.4, pwc 0.19.0) in both locales: boot clean, three crates settle on the ground, the spawn button works, a synthesized primary-button click removes a settled crate, Clear removes every element and its engine entity, console stays free of warnings. The en/ja fences are byte-identical outside comment lines.
Corrected entity-reference grammar (post playcanvas/web-components#433)
The Attributes page's Entity References section now documents the closed two-form grammar, with new subsections on nearest-first name resolution, document-wide
#references, and the unresolved-reference warnings (including the escaped#idmigration hint for legacy bare ids). The stale "CSS selector, element id, or entity name" wording is corrected on every page that carried it:pc-button(image),pc-scrollbar(handle),pc-scroll-view(usage note),pc-joint(entity-a/entity-b),pc-script-instanceand the scripting page'sentity:prefix — all en + ja.Note: the grammar in web-components#430/#431/#433 is on the library's
mainbut not yet in a tagged release (npm latest is 0.19.0). The live examples pin 0.19.0 and none of them depend on the changed semantics (all existing fences use#references, and the new guide's example uses no entity references), so nothing regresses; the usual pins bump when 0.20.0 ships needs no doc changes here.Verification
npm run lint— cleannpm run build— clean for en and ja (all links and anchors validated; ja headings carry explicit English IDs)🤖 Generated with Claude Code