docs: document part tracking (ja/en) - #241
Merged
Merged
Conversation
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.
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.
SpriteStudioPartAttachment2Dhas been in the tree since #185 with no documentation at all — it appears in neitherdocs/ennordocs/ja, andframe_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: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.get_part_names/get_part_index/get_part_transform/is_part_hidden) with theframe_updatedsignal, and a GDScript example. Includes the note that a one-shot query (a projectile spawn point) is simpler than placing a node.frame_updated, emitted right after the player's update and before the render phase, in whichever processanimation_process_modeselects.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:
Transform2Dcarries the whole 2x3 affine, so withupdate_position/update_rotation/update_scaleall on,_apply_transformassigns 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 theRemoteTransform2Dbehaviour;update_scaleis off by default, so the default is position + rotation.global_transformas sampled whenframe_updatedfired, so moving the player afterwards lands on the target a frame later. Kept as a warning, same as the Unity page.RigidBody2Dmust not be a target (useAnimatableBody2Dwithsync_to_physics, and set the player'sanimation_process_modetoPhysicsso tracking is driven on the physics frame); draw order is not tracked, so a tracked node is never slotted between SpriteStudio parts;Controlcannot be a target.API reference fixes
docs/{en,ja}/api/player.md:frame_updatedadded 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 onSsAnimeBinary(parts: [PartData]alongsideanimations: [AnimationData]), one list per.ssabshared by every animation in it, and_rebuild_part_index_map()builds the map once per resource insetSSABResource(). The description is now asset-wide.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. Onlyautoplayis behind anis_editor_hint()guard, soNOTIFICATION_INTERNAL_PROCESS— and theframe_updatedemit at the end of it — runs in the editor as well. Worth a glance during review if anyone has a scene handy.