BabylonJS
Update .babylon File Format Doc
Refresh and update the documentation page that talks about what is included in the .babylon file format.
See forum thread for reference: https://forum.babylonjs.com/t/babylon-file-format-documentation/25057/3
What do you think about creating an official JSON schema for the .babylon format, and using that as a significant part of the official documentation of the file format? I've already started the process in my VS Code workspace, to better understand the format, myself. The process is straightforward, if a bit tedious the first time (updates are quick).
If desired, I volunteer to finish the schema documentation process and contribute it here.
The primary advantage of this approach is better parity between the documented format and code "in the wild". In particular, compliant editors (such as VS Code) can point out divergence from the spec. Also, schema validation tools can be used to ensure that a particular file matches the current schema. This could be used as a presubmit check for the playground, or to the main repo, or wherever it's deemed useful. (Likely not on the critical path of Babylon itself, to avoid size/performance penalties).
If you go this route, I also recommend it be published to a canonical URI on the babylon.js site for easy reference by tools such as VS Code.
Cheers, Brian
I like the idea of having a schema for the babylon file. I believe this was never a high priority because this type of file is usually expected to be exported from an editor such as Blender, and not be manually edited.
We will not add any validation tools to the framework itself, but as you say it will be a great tool for people using IDEs like VS Code that can validate the file.
OK, I finished a version of the schema. There's probably some issues, but it's hard to tell without more examples. I was happy with the ability of the schema to capture the information currently documented on the format, including: comments, default values, optional values, enumerated types, etc. The only thing it wasn't able to capture was the notion of an explicit type "ReflectionProbe" that inherits from Texture. Instead, I added all of the RenderTarget and ReflectionProbe fields to the Texture type.
Assuming things look good, the next question is how to best make it useful. I've already included it in a vscode extension that I'm working on (that's where the schema is checked in). That might be enough. It could also be hosted on the main site as a canonical json schema, with it's own URI. The documentation site could also be updated to use the schema as the "source-of-truth" for the file format. I'd be happy to contribute work in any of these areas, if desired.
Cheers, Brian
@bmcbarron - Would you be interested in writing up the documentation based on the schema? This is constantly falling off our todo list as we have other competing priorities.
Hi @thomlucc , I can find time to do this before the end of the year. In order for it to be of lasting use, I'd like to do it this way:
- Check in the schema to the repo and link from the documentation page (alongside the current loader code link).
- Add a devDependency on a json validator, and add it to any unit tests of the babylon file format reading/writing (adding one if there isn't already). This helps avoid accidental changes to the schema, and encourages intentional ones to keep the schema in sync.
- Check in a script that programmatically generates the schema documentation page from the schema itself. That way the documentation can always be up to date.
- Add a link to my vscode extension, which provides intellisense for .babylon files, as well as a viewer for .babylon files. If desired, we can move the extension project to live under the BabylonJS github root for credibility and/or shared maintainability.
What do you think?
@bmcbarron - Sorry I did see the notification for your response (seeing it now as we do our quarterly grooming). Pinging @RaananW
Hi @bmcbarron , sorry again for such a late response.
I think the next steps is for us to fully test the schema, and these 2:
- Check in the schema to the repo and link from the documentation page (alongside the current loader code link).
Most, if not all of our .babylon files are on the assets library, and we have the babylon file in typescript ytpings, so I am not sure the main repo is the right place for this. Adding it to the doc repository makes more sense to me, allowing to download it or see it on github.
- Add a link to my vscode extension, which provides intellisense for .babylon files, as well as a viewer for .babylon files. If desired, we can move the extension project to live under the BabylonJS github root for credibility and/or shared maintainability.
This is amazing - I will be happy to download and test it!