Skip to content

docs: generated assets, their dependencies, and getting them into a build - #301

Merged
Naruto merged 1 commit into
developfrom
docs/generated-assets-and-packs
Sep 6, 2026
Merged

docs: generated assets, their dependencies, and getting them into a build#301
Naruto merged 1 commit into
developfrom
docs/generated-assets-and-packs

Conversation

@Naruto

@Naruto Naruto commented Sep 6, 2026

Copy link
Copy Markdown
Collaborator

Description

Adds workflow/generated_assets.md (both locales), the Godot counterpart of the page SSPlayerForUnity gained in cri-middleware/SSPlayerForUnity#144 — but the reason for it here is the opposite of Unity's.

Unity's references are GUIDs, so its editor tracks them correctly by construction. Here a .ssab reaches its textures, its sound/ audio and the .ssab an Instance part plays by building a res:// path against its own directory at runtime, and SSABResource reports no dependency list — so the editor filesystem's dependency cache for a .ssab is empty.

That is invisible until it bites. _export_find_dependencies collects by walking those deps, so Export selected scenes (and dependencies) ships the .ssab a scene references and leaves the images, the audio and the Instance target behind. Playback does not stop on a texture that failed to resolve — the parts are drawn untextured. The export succeeds, the app launches, and only the artwork is missing. The default Export all resources in the project takes every file and is unaffected, which is why nobody has hit this yet. The warning is on the new page and repeated at the top of workflow/export.md, where the mode is actually chosen.

The rest of the page is what a reader has to work out by inspection today:

  • which files land in the output folder and what each one holds — with the real layout, subfolders and sound/ included;
  • that no material and no shader is generated into the project, the shaders being built into the native library (so the four file kinds above are all there is to ship);
  • that a reconvert rewrites the binaries in place, so an image's .import (and its UID) survives, and that the collision dialog appears only when the output folder already belongs to a different .sspj;
  • that .pck resolution works across packs, because export writes each remap as a <path>.remap file inside the pack.

The .sspj / .ss*e side is player-agnostic and lives in the portal, which this links to rather than restating.

Two things deliberately differ from the Unity page, because Godot differs: the output folder is stored in .ssplayer_sources.cfg and is therefore shared by the team (Unity's is per-person in EditorUserSettings), and moving the folder afterwards does not carry the .sspj binding with it — there is no move/rename hook on this side, so the page points at the existing relink procedure instead of promising the move is tracked.

Also corrects workflow/import.md (English only): the converter writes <sspj name>/, not <sspj_name>_ssab/, and it writes the referenced textures and audio there too — which is the whole reason the folder has to be copied as a unit.

Note for review

Japanese in-page anchors could not be used: mkdocs.base.yml sets no toc.slugify, so a CJK heading becomes _1, _2, … on the ja site. The ja cross-links name the section in prose instead. A follow-up PR fixes the root cause.

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings — scripts/build-docs.sh (both locales, --strict) reports no issues
  • Any dependent changes have been merged and published in downstream modules

The Unity player grew a page for this; Godot needs one for the opposite reason.
Unity's references are GUIDs, so its editor tracks them correctly by construction.
Here a `.ssab` reaches its textures, its `sound/` audio and the `.ssab` an Instance
part plays by building a res:// path against its own directory at runtime, and
SSABResource reports no dependency list -- so the editor filesystem's dependency
cache for a `.ssab` is empty.

That is invisible until it bites. "Export selected scenes (and dependencies)"
collects by walking those deps, so it ships the `.ssab` a scene references and
leaves the images, the audio and the Instance target behind. Playback does not
stop on a texture that failed to resolve; the parts are drawn untextured. The
export succeeds, the app launches, and only the artwork is missing. The default
"Export all resources in the project" takes every file and is unaffected, which
is why nobody has hit this yet. The warning is on the new page and repeated at
the top of the export page, where the mode is chosen.

The rest is what a reader has to work out by inspection today: which files land
in the output folder and what each one holds; that no material and no shader is
generated into the project, the shaders being built into the native library;
that a reconvert rewrites the binaries in place, so an image's `.import` -- and
its UID -- survives, and that a collision dialog appears only when the output
already belongs to a different `.sspj`; and that `.pck` resolution works across
packs because the pack carries its own `.remap` files.

The `.sspj` / `.ss*e` side is player-agnostic and lives in the portal, which this
links to rather than restating.

Also correct the English CLI page: the converter writes `<sspj name>/`, not
`<sspj_name>_ssab/`, and it writes the referenced textures and audio there too --
which is the whole reason the folder has to be copied as a unit.
@Naruto
Naruto merged commit 43bb4e5 into develop Sep 6, 2026
0 of 2 checks passed
@Naruto
Naruto deleted the docs/generated-assets-and-packs branch September 6, 2026 07:38
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