RhapsodyInGeek
commented
2 months ago There is also a new table added to the funcGodotMap class talking about the methods. I'm unsure about how best to list the parameters for the unwrap_uv2 method, since it's an optional parameter.
You should write the function name exactly as it is defined in the GDScript file: unwrap_uv2(node: Node = null). Additionally, we should specify the return type as well, even if the return type is just void.
To maintain consistency across the plugin and the documentation, use the official description comments found in the script files rather than creating your own. So for unwrap_uv2:
Recursively unwrap UV2s for
nodeand its children, in preparation for baked lighting. And for verify_and_build(): _Verify that FuncGodot is functioning and that [member map_file] exists. If so, build the map. If not, signal [signal buildfailed]
Functions should be listed in the order that they appear in the script files, just like signals and properties do.
If a description is inaccurate, definitely report it on the plugin issues.
Also, this is on me in a way since I'm pretty sure I added the signals in the reference, but we should order things the same way the Godot docs do, I think. So it should be Properties first, Methods second, Signals third. Don't worry about changing that though, I'll go through all the reference pages and fix it all at once.
There is a new page under tips and tricks titled runtime map building.
I think we shouldn't jump the gun on it quite yet. We first need a project set up for minimal steps to runtime building so that we can make any tutorial on it follow that. That means a project with nothing but an unmodified func_godot, a simple map, and a scene with a single custom script to perform runtime building on _ready() or on key press. When we have that, we can then document the steps to recreate that and write the Runtime Building Tips page based on that project, so that we know exactly what is needed.
Should we be documenting the import limitation for exported files? Since it's a pitfall that doesn't have an obvious solution and affects current stable build and the current 4.3 build(both requiring either of the other 2 import options selected instead of QuakeMap) I'm in favour of keeping this.
I think it's worth documenting. I admittedly don't think it'll really be an issue for most users since runtime building is more likely going to be used for custom maps which will be external files anyway, and the problem is caused by Godot saving packed .map files as .tres. That said, it's an opaque issue that can affect devs trying to do procedural map building with map files packaged with the PCKs on export, so to save those few the hassle of figuring it out we should document how the behavior of Godot's resource packing can affect runtime building of internal map files.
A couple other notes on the Runtime Building page:
- Notes in tutorial sections (not the reference tables) should be formatted as
<blockquote><i>NOTE: Note text</i></blockquote>. - The Tip pages shouldn't have Tip: Text bits. As the whole page itself is a set of tips, treat it as just another paragraph on the page. If you need to emphasize that it's a different aspect under the same subject, use a header tag like
<h2>or<h3>. - Any code block examples should try to stay as close to the func_godot code style as possible rather than your own personal style, for consistency across the docs and the plugin snippets itself. The main bits being camel case limited to classes, snake case used for methods, properties, and signals.
I appreciate the efforts and enthusiasm for trying to improve the docs though. Usually feels like a sorely neglected aspect of most tools out there.
RisingThumb
sinewavey
We should replace the TB image again, but this time with this because `${MAP_FULL_NAME} is a better option (it includes the .map extension).
This should resolve #4
@sinewavey I'd be interested to hear your insight on this since I know you have a lot more runtime map building experience than I do, is there anything obvious I'm missing here. @RhapsodyInGeek what are your thoughts on this, about what should and shouldn't be included here?
There is a new page under tips and tricks titled runtime map building. There is also a new table added to the funcGodotMap class talking about the methods. I'm unsure about how best to list the parameters for the unwrap_uv2 method, since it's an optional parameter.
Additionally under the runtime map building page, I've noted that it's left to the user to bake what they want. I'm unsure if what we should be saying about the unwrap UV2 method here. idk how useful this is currently with this issue still existing https://github.com/godotengine/godot-proposals/issues/8656#issuecomment-2052287278
Should we be documenting the import limitation for exported files? Since it's a pitfall that doesn't have an obvious solution and affects current stable build and the current 4.3 build(both requiring either of the other 2 import options selected instead of QuakeMap) I'm in favour of keeping this.
I have also documented the tip about using command line argument to pass map files as a launch option for Trenchbroom(Similar to Sinewave's point about this in the Discord for radiant). It's one of the cool not-so-obvious benefits of runtime map building
You can preview these changes here: https://risingthumb.github.io/func_godot_docs/FuncGodot%20Manual/FuncGodot%20Manual.html