Skip to content

docs: document the per-part Override Layer API - #234

Merged
MasamiYitsuse merged 1 commit into
developfrom
feature/add-document-override_API
Jul 21, 2026
Merged

MasamiYitsuse merged 1 commit into
developfrom
feature/add-document-override_API

Conversation

@MasamiYitsuse

Copy link
Copy Markdown
Collaborator

Summary

The per-part Override Layer (Phase 2) has been wired into SpriteStudioPlayer2D since 16eb25a, but nothing in docs/ 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.md

Adds a Part Overrides (Color / Cell / Visibility) section after the existing texture-swap section: intro, GDScript example, method table, blend_op / priority value tables, and the caveats list. A note distinguishes it from set_cellmap_texture(), which is whole-cellmap rather than per-part.

docs/{ja,en}/api/player.md

Adds 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's 65_override_layer.ja.md:

  • Argument order. Unity is SetPartColorOverride(part, blendOp, color, …); the Godot binding takes the Color first: set_part_color_override(part_name, color, blend_op, priority). Defaults are documented as bound (blend_op = 0, priority = 1, cascade = false).
  • No enums. The node does not BIND_ENUM_CONSTANT either parameter, so GDScript passes raw ints. There is no SpriteStudioBlendOp.Mul equivalent to write, hence the value tables.
  • No four-corner variant. ss_runtime_set_part_color_override_corners exists 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.
  • Cell name enumeration lives elsewhere. get_cellmap_names() / get_cell_names() are on SSABResource, not on the player as in Unity, so the example goes through get_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, so set_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.md into usage_scripting.md are plain page links with no #anchor. mkdocs.yml does not override the toc slugify, 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. mkdocs is not installed in this environment, so mkdocs build --strict was not run — worth letting the docs CI confirm.

Open question

The > [!NOTE] in api/player.md was kept, matching the callout already in that file. The usage_scripting.md section instead uses the > **… について**: style consistently. Happy to unify either way if reviewers prefer one.

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.
@MasamiYitsuse
MasamiYitsuse merged commit 24c41dc into develop Jul 21, 2026
2 checks passed
@MasamiYitsuse
MasamiYitsuse deleted the feature/add-document-override_API branch July 21, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant