docs: generated assets, their dependencies, and getting them into a build - #301
Merged
Conversation
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.
10 tasks
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.
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
.ssabreaches its textures, itssound/audio and the.ssaban Instance part plays by building ares://path against its own directory at runtime, andSSABResourcereports no dependency list — so the editor filesystem's dependency cache for a.ssabis empty.That is invisible until it bites.
_export_find_dependenciescollects by walking those deps, so Export selected scenes (and dependencies) ships the.ssaba 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 ofworkflow/export.md, where the mode is actually chosen.The rest of the page is what a reader has to work out by inspection today:
sound/included;.import(and its UID) survives, and that the collision dialog appears only when the output folder already belongs to a different.sspj;.pckresolution works across packs, because export writes each remap as a<path>.remapfile inside the pack.The
.sspj/.ss*eside 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.cfgand is therefore shared by the team (Unity's is per-person inEditorUserSettings), and moving the folder afterwards does not carry the.sspjbinding 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.ymlsets notoc.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
Checklist:
scripts/build-docs.sh(both locales,--strict) reports no issues