Skip to content

docs: document part tracking (ja/en) - #241

Merged
MasamiYitsuse merged 1 commit into
developfrom
feature/add-document-parts-tracking
Jul 27, 2026
Merged

MasamiYitsuse merged 1 commit into
developfrom
feature/add-document-parts-tracking

Conversation

@MasamiYitsuse

Copy link
Copy Markdown
Collaborator

SpriteStudioPartAttachment2D has been in the tree since #185 with no documentation at all — it appears in neither docs/en nor docs/ja, and frame_updated, the signal that drives it, was missing from the signals table. This adds a Part Tracking section to the scripting page in both languages, mirroring the structure and voice of the section SSPlayerForUnity uses for the same feature, so the two players read alike.

What was added

docs/{en,ja}/workflow/usage_scripting.md, placed before Part Overrides to match the Unity page's ordering:

Intro + property table The node is constraint-style: the player never creates or frees nodes, you own the target's lifecycle. Table covers part_name / follow_path / remote_path / use_global_coordinates / update_position / update_rotation / update_scale / on_part_hidden, with the inspector labels alongside the property names.
Querying from a script The player-side API (get_part_names / get_part_index / get_part_transform / is_part_hidden) with the frame_updated signal, and a GDScript example. Includes the note that a one-shot query (a projectile spawn point) is simpler than placing a node.
Timing and accuracy Driven by frame_updated, emitted right after the player's update and before the render phase, in whichever process animation_process_mode selects.
Notes Visibility takeover, Instance-part parts being out of reach, duplicate part names, automatic re-resolve on an asset swap, draw order, Control, edit mode.

Where the text departs from the Unity wording

The Unity doc's accuracy caveats are Unity's, not ours, so the text follows this implementation instead:

  • The pose is exact, everywhere in the tree. A Transform2D carries the whole 2x3 affine, so with update_position / update_rotation / update_scale all on, _apply_transform assigns it wholesale — skew and negative scale included — whether the target is a child of the player or in a separate hierarchy. Unity has to decompose and approximate; we do not, and the doc says so. Turning any of the three off falls back to component-wise writes (skew not preserved), which is the RemoteTransform2D behaviour; update_scale is off by default, so the default is position + rotation.
  • The one-frame lag does apply here. The pose is written from the player's global_transform as sampled when frame_updated fired, so moving the player afterwards lands on the target a frame later. Kept as a warning, same as the Unity page.
  • Godot-specific notes with no Unity counterpart: RigidBody2D must not be a target (use AnimatableBody2D with sync_to_physics, and set the player's animation_process_mode to Physics so tracking is driven on the physics frame); draw order is not tracked, so a tracked node is never slotted between SpriteStudio parts; Control cannot be a target.

API reference fixes

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

  • frame_updated added to the signals table — it was bound and emitted but undocumented.
  • get_part_names() was described as returning the current animation's parts. Parts live on SsAnimeBinary (parts: [PartData] alongside animations: [AnimationData]), one list per .ssab shared by every animation in it, and _rebuild_part_index_map() builds the map once per resource in setSSABResource(). The description is now asset-wide.
  • Pointer from the Part queries section to the new workflow section. Page-level link, no anchor, since the site's slugify does not produce stable anchors for Japanese headings.

Verification

Docs only — no code, no build impact. The EN and JA files stay line-for-line parallel (258 / 258 and 151 / 151).

Every documented behaviour is taken from the current implementation (ss_part_attachment_2d.cpp, ss_player_node_2d.cpp, ss_internal_player.cpp) except one: the closing note that tracking also applies in edit mode is derived from the code, not observed. Only autoplay is behind an is_editor_hint() guard, so NOTIFICATION_INTERNAL_PROCESS — and the frame_updated emit at the end of it — runs in the editor as well. Worth a glance during review if anyone has a scene handy.

SpriteStudioPartAttachment2D shipped undocumented. Add a Part Tracking
section to the scripting page, mirroring the structure and voice of the
SSPlayerForUnity doc: the node's properties, the player-side query API
(get_part_names / get_part_index / get_part_transform / is_part_hidden)
together with the frame_updated signal, the drive timing, and a notes
block.

Where the engines differ, the text follows this implementation rather
than the Unity wording. A Transform2D carries the whole affine, so with
update_position / update_rotation / update_scale all on, the target
matches the part exactly - skew and negative scale included - wherever
it sits in the tree. The one-frame lag for a target outside the player's
subtree does apply here as well, because the pose is written from the
player's global_transform as sampled when frame_updated fired.
Godot-specific notes cover RigidBody2D (use AnimatableBody2D with
sync_to_physics, and animation_process_mode = Physics so tracking is
driven on the physics frame), draw order not being tracked, and Control
not being a valid target.

Also fill two gaps in the API reference: frame_updated was missing from
the signals table, and get_part_names was described as returning the
current animation's parts. Parts live on the SsAnimeBinary - one list
per .ssab, shared by every animation in it - so the list is asset-wide.
@MasamiYitsuse
MasamiYitsuse merged commit 7eb8f85 into develop Jul 27, 2026
2 checks passed
@MasamiYitsuse
MasamiYitsuse deleted the feature/add-document-parts-tracking branch July 27, 2026 07:01
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