docs: document the per-part Override Layer API - #234
Merged
Merged
Conversation
Mirror the Part Overrides section from SSPlayerForUnity, adapted to the GDScript surface of SpriteStudioPlayer2D, and add the matching entries to the API reference. The Godot bindings differ from the Unity ones in ways the wording has to follow: the color override takes the Color before the blend op, and neither blend_op nor priority is bound as an enum, so both are documented as plain integers with a value table. The four-corner color variant exists in the runtime but is not exposed on the node, so only the single-color form is described. Cell/cellmap name enumeration lives on SSABResource rather than the player. Also note the Godot-specific caveat that the redraw dedup in SsInternalPlayer::update() keeps an override off screen while playback is stopped, paused, or otherwise not advancing the frame, and that set_frame(get_frame()) forces the rebuild. Cross-references are plain page links: mkdocs does not override the default ASCII slugify, so Japanese headings would not produce usable anchors, and English anchors would differ between GitHub and the built site.
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
The per-part Override Layer (Phase 2) has been wired into
SpriteStudioPlayer2Dsince16eb25a, but nothing indocs/mentioned it — the only "override" the documentation covered was the older whole-cellmap texture swap. This adds the missing user-facing documentation, in both languages.The Part Overrides section from SSPlayerForUnity (
docs/ja/workflow/usage_scripting.md) is mirrored as closely as the two APIs allow, so that a reader moving between the two players finds the same structure and the same wording.Changes
docs/{ja,en}/workflow/usage_scripting.mdAdds a Part Overrides (Color / Cell / Visibility) section after the existing texture-swap section: intro, GDScript example, method table,
blend_op/priorityvalue tables, and the caveats list. A note distinguishes it fromset_cellmap_texture(), which is whole-cellmap rather than per-part.docs/{ja,en}/api/player.mdAdds Part queries (
get_part_names/get_part_index/get_part_transform/is_part_hidden, none of which were documented either) and Part overrides subsections with the full signatures and the two value tables.Where the Godot wording had to diverge from Unity
Each of these was checked against
ss_player_node_2d.{h,cpp},ss_internal_player.cpp, and the SDK's65_override_layer.ja.md:SetPartColorOverride(part, blendOp, color, …); the Godot binding takes theColorfirst:set_part_color_override(part_name, color, blend_op, priority). Defaults are documented as bound (blend_op = 0,priority = 1,cascade = false).BIND_ENUM_CONSTANTeither parameter, so GDScript passes raw ints. There is noSpriteStudioBlendOp.Mulequivalent to write, hence the value tables.ss_runtime_set_part_color_override_cornersexists in the runtime but is not exposed on the node, so the docs describe the single-color form only and do not carry over Unity's "four-corner overload" wording.get_cellmap_names()/get_cell_names()are onSSABResource, not on the player as in Unity, so the example goes throughget_ssab_resource().Godot-specific caveat added
SsInternalPlayer::update()skips the rebuild when the draw frame has not changed (ss_internal_player.cpp:814-815), and returns even earlier when playback is not running. Setting or clearing an override while stopped, paused, or on a frame that does not advance therefore has no visible effect until playback moves on.setFrame()calls_seek_and_redraw()unconditionally, soset_frame(get_frame())is documented as the way to force it. This is the same trap the SDK documentation records under §5-1 as one the Unity player hit.Note on cross-reference links
The links from
api/player.mdintousage_scripting.mdare plain page links with no#anchor.mkdocs.ymldoes not override thetocslugify, so it runs the default ASCII one: Japanese headings collapse to empty slugs (falling back to_1,_2, …), and an English heading containing" / "slugifies to single hyphens on the built site but double hyphens on GitHub. Page-level links are correct in both renderers.Verification
Reviewed rendered structure in both languages; the two files are section-for-section aligned.
mkdocsis not installed in this environment, somkdocs build --strictwas not run — worth letting the docs CI confirm.Open question
The
> [!NOTE]inapi/player.mdwas kept, matching the callout already in that file. Theusage_scripting.mdsection instead uses the> **… について**:style consistently. Happy to unify either way if reviewers prefer one.