docs(light): tighten LightComponent JSDoc#8667
Merged
Merged
Conversation
Comprehensive pass over the LightComponent public API documentation:
Factual fixes
- cookieFalloff default corrected from `false` to `true`
- affectSpecularity description updated to reflect that the value is now
preserved on the component and re-applied if the type later becomes
directional (rather than being silently dropped for non-directional types)
- 'Onmi' typo in the class-level example link list
- Missing close paren in the SHADOWUPDATE_THISFRAME bullet
- 'shadow update model' -> 'shadow update mode'
- shadowBlockerSamples 'this values' -> 'this value'
Defaults added to setter docs
- shadowType, vsmBlurMode, vsmBias, cookieAsset, cookie, cookieChannel,
cookieAngle, cookieScale, cookieOffset, mask, affectDynamic,
affectLightmapped, bake, bakeDir, isStatic, layers, shadowUpdateOverrides
Style / consistency
- Drop `pc.` prefix on `pc.LIGHTSHAPE_PUNCTUAL` -> `{@link LIGHTSHAPE_PUNCTUAL}`
- Unify 'Defaults to N.' phrasing across the file
- type setter cross-links LIGHTTYPE_DIRECTIONAL/OMNI/SPOT and documents the
'point' backwards-compat alias
- color setter notes sRGB color space
- shadowUpdateOverrides 'undefined' -> 'null' (matches the actual default)
Clarity rewrites
- bakeArea description rewritten to describe what it actually does
- mask description expanded to explain bit composition and helper interaction
- shadowSamples 'must be' -> 'should be' (setter does not validate)
- cookie / cookieAsset clarify spot wants a 2D texture and omni a cubemap
- bakeDir grammar pass
- vsmBlurSize 'uneven' -> 'odd; even values are rounded up to the next odd'
Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
There was a problem hiding this comment.
Pull request overview
JSDoc-only cleanup pass over the public LightComponent API to improve correctness and consistency (defaults, links, phrasing), without changing runtime behavior.
Changes:
- Corrects/clarifies several property defaults and behaviors (e.g.,
cookieFalloff,shadowUpdateMode,affectSpecularity). - Improves cross-linking and wording consistency across the API docs (constants, “Defaults to …” phrasing, examples).
- Expands explanations for a few more nuanced properties (e.g.,
mask,bakeArea, cookie texture expectations).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The setter accepts strings, not the numeric constants, so linking the LIGHTTYPE_DIRECTIONAL/OMNI/SPOT constants alongside the string aliases invited confusion about which form to pass. Co-authored-by: Cursor <cursoragent@cursor.com>
The 'point' value is still tolerated by the runtime for legacy data, but it was removed from the public API long ago and shouldn't be advertised in user-facing JSDoc. Co-authored-by: Cursor <cursoragent@cursor.com>
The affectDynamic / affectLightmapped / bake helpers maintain their own
private backing fields and are not recomputed from mask. The previous
wording ("manipulate the same underlying mask") implied a bidirectional
view; spell out that writes are one-way and the helpers can overwrite
each other.
Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Reword the type setter bullets to match the class-level descriptions (the previous "spot: an omni-directional light but is bounded by a cone" was self-contradictory). - Replace the stale "Gets the penumbra angle in degrees" wording on the bakeArea getter with the same description used by the setter. Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The getter returns `_cookieAssetId` (number|null) but the JSDoc still read "Gets the texture asset…", which implied an Asset instance. Co-authored-by: Cursor <cursoragent@cursor.com>
The public LightComponent#type setter takes strings ("directional",
"omni", "spot"), so referring to the internal numeric LIGHTTYPE_*
constants in user-facing setter docs was mixing the two APIs. Switch
both occurrences (affectSpecularity, bakeArea) to the string form.
Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
`bake` and `bakeDir` are public properties of LightComponent and the
file already uses {@link bake} elsewhere (mask, affectLightmapped). Fix
the remaining stray backtick references in bakeArea and bakeDir for
consistency and to give readers a clickable link to the related
property.
Co-authored-by: Cursor <cursoragent@cursor.com>
`type` is a public property on LightComponent, so the prose mentions in
the affectSpecularity and bakeArea setter docs should use {@link type}
for consistency with the rest of the property cross-references.
Co-authored-by: Cursor <cursoragent@cursor.com>
Setting cookieAsset to an Asset instance still works but is a legacy
back-compat shim that we don't want to advertise to new callers. The
setter is documented as taking an asset id, matching the {number|null}
type annotation and the getter's return value.
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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
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.
Summary
Comprehensive JSDoc pass over the public
LightComponentAPI. No runtime changes.Factual fixes
cookieFalloffdefault corrected fromfalsetotrueto matchLight._cookieFalloff = true.affectSpecularitydescription updated to reflect the new behaviour from refactor(light): align LightComponent with CameraComponent architecture #8666: the value is now preserved on the component and re-applied if the type later becomes directional (rather than silently dropped for non-directional types).bakeAreagetter description was a stale"Gets the penumbra angle in degrees."— replaced with a description matching the rewritten setter.cookieAssetgetter description implied anAssetinstance was returned — corrected to match the actual{number|null}return type (the asset id, ornull).Clustered Onmi Shadows→Clustered Omni Shadows.SHADOWUPDATE_THISFRAMEbullet.shadow update model→shadow update mode(twice).shadowBlockerSamples:this values→this value.Defaults added to setter docs
shadowType,vsmBlurMode,vsmBias,cookieAsset,cookie,cookieChannel,cookieAngle,cookieScale,cookieOffset,mask(now linked toMASK_AFFECT_DYNAMIC),affectDynamic,affectLightmapped,bake,bakeDir,isStatic,layers,shadowUpdateOverrides.Style / consistency
pc.prefix onpc.LIGHTSHAPE_PUNCTUALand switch to{@link LIGHTSHAPE_PUNCTUAL}to match every other constant reference in the file.Defaults to N.phrasing.typesetter bullets reworded to mirror the class-level type descriptions (the previous"spot"line — "an omni-directional light but is bounded by a cone" — was self-contradictory).affectSpecularity/bakeArea/bakeDirsetter docs use{@link …}fortype,bakeandbakeDirinstead of bare backticks.affectSpecularityandbakeAreasetter docs refer to the public string"directional"rather than the internalLIGHTTYPE_DIRECTIONALnumeric constant (the publicLightComponent#typeis string-based).cookieAssetsetter description simplified to document the public contract (an asset id) without advertising the legacyAsset-instance shim.colorsetter notes that the value is in sRGB space.shadowUpdateOverrides:Set to undefined if not used.→Set to null if not used.(matches the actual default), and{number[] | null}→{number[]|null}to match the engine's no-spaces JSDoc convention.Clarity rewrites
bakeArearewritten — the previous description called it a "penumbra angle"; it actually controls the angular size used when baking soft shadow boundaries for a directional light into the lightmap.maskdescription expanded to explain bit composition and to spell out that theaffectDynamic/affectLightmapped/bakehelpers are backed by independent state and are not recomputed frommask(so writingmaskdirectly will not update those getters, and a subsequent helper write may overwrite bits set viamask).shadowSamples:must be a positive whole number→should be a positive whole number(the setter does not validate).cookie/cookieAsset: clarify that spot lights expect a 2D texture and omni lights a cubemap.bakeDir: minor grammar pass.vsmBlurSize:Only uneven numbers work, even are incremented.→Only odd values are supported; even values are rounded up to the next odd value.Public API changes
None. Doc-comment-only.
Test plan
npm run lintclean.npm run build:typessucceeds.npm run test:typessucceeds (verifies the generated.d.ts).