Runtime map building + funcGodotMap function reference

[RisingThumb]

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 godotengine/godot-proposals#8656 (comment)

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

[RhapsodyInGeek]

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 node and 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 build_failed]

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]

Thanks for the comprehensive review!

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.

I've raised a separate issue for this and other "across the entire docs" issues can be addressed in one whole lot.

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.

I think this would be best added to the the func_godot_example_basic repo. I can put together a basic example for this when I get the time. Or should this be in the test repo? I think it's more demonstrative than it is testing. Do you think we should be tutorialising it? I think making an example, pointing to it in the example repo and just making it known that you can do this and the common pitfalls would be sufficient imo.

I'll take a look at addressing the other simpler parts of this review when I get more free time to look at it later this week

[RhapsodyInGeek]

Added a runtime building example project:
https://github.com/func-godot/func_godot_runtime_building

[sinewavey]

Sorry I completely missed this in the haze of traveling around the US and returning back home.

I think you hit the primary points of it pretty well.
Regarding the last tip line - I actually just wrote a docs page on that without realizing this existed 😅
I think it'd be wise to consider uniting the two.

Lightmap building is something that you can't currently do in runtime or exported builds; only the editor. Coincidentally, I've been looking into writing a q3map2-like "Compiler" that will still allow users to save a .map, run a compiler program, and get a .tscn with the baked lightmap data and scene ready to play, much like the process goes in Quake.

With what Tim has mentioned regarding VoxelGI, it makes me think: why can't any node like that (define an area to bake) work this way? If particleSDF fields can be baked outside of the editor, it'd be another useful tool to expose. And in that case, I think the two sections almost deserve a different approach with discussing those steps proper, with a breakdown of runtime vs in editor for each.

That said, good lord is this a process to figure out so far as it's heavily intertwined with the Godot UI.

[RisingThumb]

Regarding the last tip line - I actually just wrote a docs page on that without realizing this existed 😅

Personally, I think they should be separated. One is about launching within an editor(which is most useful with runtime map building, there probably exists other reasons to use it but idk), and the other is about runtime map building. I'll remove this tip from the page since your PR addresses it

Lightmap building is something that you can't currently do in runtime or exported builds; only the editor. Coincidentally, I've been looking into writing a q3map2-like "Compiler" that will still allow users to save a .map, run a compiler program, and get a .tscn with the baked lightmap data and scene ready to play, much like the process goes in Quake.

Imo, all that needs to be done is for the upstream work to be done on exposing lightmap baking in the node, and adding a --compile-lightmaps CLI arg. Once that's done, you compile it at runtime, to spit out a .lmbake file that's used every other time when loading the map.

[sinewavey]

Imo, all that needs to be done is for the upstream work to be done on exposing lightmap baking in the node, and adding a --compile-lightmaps CLI arg. Once that's done, you compile it at runtime, to spit out a .lmbake file that's used every other time when loading the map.

In theory it's pretty simple. In practice... it's a lot more complicated, from a cursory glimpse at how the LightmapGI stuff even works in the editor.

Exposing it to the user: yes. Actually getting this feature: that's a doozy.

[RisingThumb]

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 node and 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 build_failed]

I've made this change. For the parts using [code][/code] and [member] and [signal] I've changed these to just be <code></code> tags. I believe these are some form of markdown docs comment, but idk. Happy to retain that, but I think it looks bad like that

Personally, I think they should be separated. One is about launching within an editor(which is most useful with runtime map building, there probably exists other reasons to use it but idk), and the other is about runtime map building. I'll remove this tip from the page since your PR addresses it

In addition, I've made this change. @sinewavey if this gets merged in before your PR, it might be worthwhile adding a note and a link forward under this page about launching straight from the editor being one of the benefits of this.

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.

I have linked forward to the example repository you made and I've copied the script over verbatim.

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.

This has been left to be addressed in #9 . Any further thoughts are welcome, happy to make other small changes! 👍

[sinewavey]

In addition, I've made this change. @sinewavey if this gets merged in before your PR, it might be worthwhile adding a note and a link forward under this page about launching straight from the editor being one of the benefits of this.

Yep, if the other docs are updated, as would my proposed PR page until it's live. Part of submitting PRs - includes fixing other ones if needed.

[RhapsodyInGeek]

Personally, I think they should be separated. One is about launching within an editor(which is most useful with runtime map building, there probably exists other reasons to use it but idk), and the other is about runtime map building. I'll remove this tip from the page since your PR addresses it

They should be together. Launching from the editor is made possible through runtime / @tool scripted building. Runtime Build page would best be:

---

Runtime Building

• Describe what Runtime Building is (obvious to us but not to everyone)
• State runtime building can be used for proc gen
• State runtime building can be used to build from chosen map editor via command line

Setting Up Runtime Building In Godot

• Verify and Build explanation
• Build signals explanation
• Unwrap UV2 and UV2 signal explanation
• NOTE: LightmapGI baking information
• Code block example (use runtime_build example script)

Using Command Lines To Build From Map Editors

• Quick overview of running Godot with command line args
• Quick general description of building from editor

Building from TrenchBroom

• TrenchBroom process

Building from NetRadiant Custom

• NetRadiant Custom process

---

We should also check if JACK is capable of it, too.

[RisingThumb]

They should be together. Launching from the editor is made possible through runtime / @tool scripted building. Runtime Build page would best be:

I've added this back in the previous minimal form. I've addressed the structure changes too. Thanks for the quick reviews btw! 👍

@sinewavey would it be possible for #10 to be reworked slightly to go in the section where I've currently got the brief text about using command lines to build from map editors?

[sinewavey]

Easily. The language and wording of it should practically be ready to copy/paste in to your PR if you like.

[RisingThumb]

Easily. The language and wording of it should practically be ready to copy/paste in to your PR if you like.

Up to you, personally, I'd prefer separate PRs, but I'm happy to combine them both into this PR

[RisingThumb]

@sinewavey bumping in case this has been missed, If there's no preferences I'd like to go forward with this PR so this information is available instead of hidden away

[sinewavey]

@sinewavey bumping in case this has been missed, If there's no preferences I'd like to go forward with this PR so this information is available instead of hidden away

Absolutely. I'll go ahead and close mine.

[RisingThumb]

@sinewavey bumping in case this has been missed, If there's no preferences I'd like to go forward with this PR so this information is available instead of hidden away

Absolutely. I'll go ahead and close mine.

I'll look at adding the stuff from your PR into this when I get some time later this week, thanks! 👍

[RisingThumb]

Merged it @sinewavey

[RhapsodyInGeek]

I was thinking about this, you can probably use the Run > Compile Map option as another way of compiling/launching maps, but I haven't dug into it 🤔

Might be worth looking into! A good reliable method to automatically grab the map's global folder location would be useful. I'd do it myself, but I'm currently trying to solve func-godot/func_godot_plugin#15

[sinewavey]

With this PR the NRC section should probably mention the adjustments

[RisingThumb]

Might be worth looking into! A good reliable method to automatically grab the map's global folder location would be useful. I'd do it myself, but I'm currently trying to solve func-godot/func_godot_plugin#15

This works. You could also probably define alternative profiles for when you want to do any preprocessing for the map(lightmap baking, navmesh baking, etc to save those). See the screenshot below. The tool path is just the path to wherever godot.exe lives. It doesn't even necessarily have to be godot.exe if you want to use a different tool beforehand to prepare the level.

Working directory is only necessary if you're doing things requiring relative paths. You could just as easily set the working directory to ${GAME_DIR_PATH} and then do --path ./ instead. Also yes, the parameter is the old parameter name because I haven't updated that in my project.

To be honest I think this is even simpler to explain than the launch engine solution. I'll do a rewrite of the currently written trenchbroom stuff to do it this way instead.

On the topic of different tools, I'm not very involved in the Quake space(beyond lurking in their mapping discord), but there's probably custom tools that effectively do the BSP step to remove faces out of bounds and covered. I can imagine a setup where you use func_godot for the point/model entities, and process the brushes in a different tool and then import it into Godot as a model. That's just an idea I have since one of the pain points I have with func_godot is the manual process of selecting all faces to be skip(even though it's intentionally design this way, it's a lot of extra control, and a lot of extra work as the cost for that control).

If you have any other ideas about those custom tools, I'd be interested to hear them. I think this would be a useful note to link to some example(common Quake .map processing tools) and some example usecases for them.

EDIT:
As an example... ericw tools to create the bsp -> bsp2obj(https://github.com/fzwoch/bsp2obj) -> godot as a model. You'd have a point model at origin representing the map, as exported from the bsp, and you'd just avoid brush entities when making your fgd.

[RhapsodyInGeek]

Spelling mistake: "somehting" should be "something"

[RhapsodyInGeek]

@sinewavey @RisingThumb Reviewing this and it all looks good to me. Are we missing anything important?

[RisingThumb]

Pushed up 2 commits.

e78d7c0 deals with what I said I'd do here that is a simpler approach to building maps(building using "Compile Maps" rather than "Launch Engine") #8 (comment) . The other 2 benefits of this, is we get to access variables that refer to the full path of the map, and to the path of the game. Up to you guys if we should go ahead with the "Compile Map" approach or the "Launch Engine" approach, can revert this commit for that, imo the former is simpler

70136f1 deals with the above PR comments. @sinewavey can you take a look at this commit in particular? I removed the line around the default_build_menu.xml before, and added it into the 2nd line about adding the build commands. The assumption here is that this is already sorted out by doing the Netradiant custom setup before, however as I don't use Netradiant custom idk if this is enough detail to use.

[sinewavey]

@RisingThumb looks good other than my mistake in titling the resource class name

[RhapsodyInGeek]

e78d7c0 deals with what I said I'd do here that is a simpler approach to building maps(building using "Compile Maps" rather than "Launch Engine") #8 (comment) . The other 2 benefits of this, is we get to access variables that refer to the full path of the map, and to the path of the game. Up to you guys if we should go ahead with the "Compile Map" approach or the "Launch Engine" approach, can revert this commit for that, imo the former is simpler

I kind of prefer this, partly due to the font, partly due to the highlighting. Also because the correct branding for FuncGodot is either "FuncGodot" or "func_godot", but not "Func godot".

I do like telling folks to use the Compile menu though, as it allows you to have any number of build profiles saved and it's good to put new devs on that track.

That said, ${GAME_DIR_PATH} fails if the path has any spaces in it, as does ${MAP_DIR_PATH}. We should probably give that a big NOTE block. If the path has spaces, putting the exact path with quotes around it works.

[RisingThumb]

That said, ${GAME_DIR_PATH} fails if the path has any spaces in it, as does ${MAP_DIR_PATH}. We should probably give that a big NOTE block. If the path has spaces, putting the exact path with quotes around it works.

Good catch, I've added this as a block note. I've also updated the image. Also had a lookover the rest of it, and made some minor corrections and fixes. Let me know if there's anything else, otherwise I'm happy with it currently

[RisingThumb]

Thinking about it, there is one more question that's left there. J.A.C.K. is previously discussed in Map Editor configuration, but there's no mention of it here. I don't use J.A.C.K., so I don't know if it's possible or just plain unknown, it may be worth opening another issue after this specifically for J.A.C.K. being mentioned here

[RhapsodyInGeek]

I'll take a look into it. I do have JACK installed, though I don't use it really.

[RhapsodyInGeek]

So looked into it. I could get it to launch but it didn't build the map. I'm guessing it wasn't running the extra commands for some reason, not too sure why. I would probably just mention briefly that tests attempting to launch maps from JACK didn't work out very well, and that while it may be possible the setup seems better suited to TrenchBroom and NetRadiant Custom. If we want to mention it at all.

But better worded than what I just wrote.

[RisingThumb]

Personally, I think this kind of detail that it didn't work in initial tests is probably better suited for a separate issue to expand this page in the docs. For now I don't think it's worth adding on the page

[RisingThumb]

Following func-godot/func_godot_runtime_building#1 I have corrected the code example slightly in f734432

[RhapsodyInGeek]

Looks good to me. Are we all happy with this?

[sinewavey]

I think we're ready to send it out, then.

[RisingThumb]

I'm happy with it