docs: add asset system contributor documentation#3121
docs: add asset system contributor documentation#3121Kryptos-FR wants to merge 7 commits intostride3d:masterfrom
Conversation
Kryptos-FR
added
area-Doc
Right now it's not very obvious, but we do have a contributors-only documentation covering engine internals, it is under https://doc.stride3d.net/latest/en/contributors/engine/architecture/index.html It's easier to navigate and discover topics through the docs than opening a markdown reader in this repo, so I would prefer if we moved this PR over there. Users can just pull the docs and point the AI to the whole thing, or just the architecture subdirectory. We could even link back to other game-specific pages of the docs from there where appropriate, which could be useful for the datacontract section for example. |
|
The Contributing / Contribute to Stride engine section is still a bit of a work in progress, so we can restructure it however we want as we add more content. The current structure was created quickly so that we would at least have a basic structure in place. |
|
I kind of disagree with moving that documentation outside the repository. It defeats its purpose:
On that last note, having to tell the AI agents to query documentation from outside (either online or by having a clone of the stride-docs folder on disk) is very expensive and wasteful. It forces the agents to read the whole doc instead of discovering parts of it while browsing through the repository as it does for any other code file, and is optimized to do. It grows unnecessarily the context window of the chat (increases dramatically the consumed tokens), making the agents less efficient. And if you forget to tell it in your prompt, it will never see these files. |
|
I don't think it makes sense to have some engine documentation here and some in the docs repo.
If the argument is that we're more likely to think of updating these if they are here rather than in the docs repo, I agree that it would, but I don't think the increase in likelihood is significant enough compared to the website, both are too far removed from the source's context. Summaries or comments, on the other hand, would have a significant increase.
There are many ways to workaround this, the most straightforward would be to simply add the directory to wherever you think would fit best, setup a symlink, ... I'm okay with moving everything we setup on the docs side back here, but we would have to setup something in the docs to fetch it from here. |
|
I agree on both side: it's nice to have tech doc around in this repo AND on the doc website. Some huge pros to have it here is it would be versioned with the code and more current than doc (which need deployment). I think we don't need the Quick note for self: if we merge this as is, I will move the tests/GPU-TESTING.md introduced in #3122 in the |
4 participants
PR Details
Add in-repo technical documentation covering the complete asset system pipeline for engine contributors and maintainers, explaining what is required to add a new built-in asset type to Stride.
Six new files under
docs/contributors/asset-system/:README.md— entry point: three-phase pipeline diagram, base-class and editor-tier decision trees, master implementation checklistruntime-type.md— runtime type attributes ([DataContract],[ContentSerializer],[ReferenceSerializer],[DataSerializerGlobal]), serialization constraints, templateasset-class.md—Assetbase class selection, required attributes, property conventions, file extensions, versioning/upgraderscompiler.md—AssetCompilerBase,Prepare,AssetCommand,GetInputFiles/GetInputTypeswith build-cache wiringeditor.md— all three editor tiers (automatic property grid →AssetViewModel<T>→AssetEditorViewModel+ XAML)registration.md— module initializers,AssemblyRegistry/AssetRegistrydiscovery chain,[YamlSerializerFactory],.sdtpltemplate filesThe existing external docs at stride3d.net cover the game-developer perspective. These docs target engine contributors, with
> [!NOTE] Game projectscallouts where the two paths diverge.Note: Anthropic's Claude contributed to writing the doc.
Motivation
We are getting contributions that touch the asset system such as #3103. It might be unclear to contirbutors how to add a new asset type, especially since it is a bit different than adding a new asset type for a game (which is already covered in the official docs).
With that said, I need to investigate how to make it work for editor-only asset types (case for #3103) which is not a scenario we have covered as of now.
One reason to have that documentation directly into the repo (and not in stride-docs) is to make it easier to both contributors and AI agents. Merging all into a single location could make it confusing for engine users (i.e. game developers) that do not care about the engine internals.
Types of changes
Checklist