Source overlay or Git submodule best practices for mod support

[jdolan]

We have some folks interested in porting Action Quake2 to Quetoo. In order to facilitate this, we should answer some of the big questions around how we'll offer mod support while continuing development of mainline Quetoo.

Quake2 was able to ship just the game source directory, with shared.{c,h} providing a small general purpose library that was adequate for compiling the game module. We have a quite a few more dependencies than that, mostly due to cgame needing to know about client, sound and renderer types. I don't think providing just a subtree of our source is viable. And, a subtree would also pin mods to a particular version of Quetoo, and frankly, the project is too fluid for that to work in the near-term anyway.

I think any approach will involve forking Quetoo. The question becomes, what is the recommended approach in order to make taking upstream updates easy? Does the mod source live in a separate sparse repository, or directly in the fork? Does the mod source provide their own build scripts, or do we provide templates? Does the mod build as part of the Quetoo build, with an argument to make? Or does it build externally to Quetoo somehow?

There's probably some proof-of-concept for this required. Help wanted.

[Raptor007]

Hi! I do code maintenance for AQ2, so I've also been hearing folks ask about this.

When I first looked into this in 2017 and saw that Quetoo had made some changes to the structures and interfaces such that you couldn't just throw in existing Quake2 mods, I had an idea in mind for a sort of quick-and-dirty approach that would essentially be an interpreter between Quetoo's mod interface and the original Q2 structures and functions in a mod like AQ2. Basically I would fork AQ2 into a Quetoo mod that exports functions which interpret Quetoo entity data into Q2 entities, run the Q2-style functions in AQ2, and finally interpret data back from AQ2's structures into the Quetoo data. It would similarly translate Q2 imports to Quetoo imports. That way AQ2 could run in Quetoo without a total rewrite and could benefit from ongoing maintenance to its Q2 code.

Unfortunately, that approach relies upon there being a stable Quetoo mod interface, and that interface being of a very similar form to Quake2, using a relatively stand-alone dynamic library with similar imports and exports. It would also rely on the general form of Quetoo not being too dissimilar to Quake2.

Would you still say in 2022 that the Quetoo project is too fluid to pin to an API of data structures and imports/exports? And is it true that it does not run its server code from a relatively independent module in the way that Quake2 does?

[Paril]

The game module runs the same way Quake II does. That part hasn't changed much.

The main issue you'd run into is that we don't use frame-based animation, so the way animations work would have to be overhauled (we support MD3 and OBJ, but we only really use MD3 for the player models and since we use Q3 player models we use the animation values from them too). Other interfaces that Q2 use direct pointers for (cvars, pmove, surfaces...) are also going to be problematic, you'd have to convert them to some equivalent structured format. For things like animated weapon models you'd need to create a cgame module that can handle those, since right now animations are only used by player models and ignored everywhere else.

It'd probably be less work to just create something new, tbh. AQ2TNG's codebase is pretty rough comparatively to what we've got here, and it'd be made a ton rougher by needing to create an intermediate layer because there's no way you'd be able to achieve it without modifying a lot of dependent code.

Having done a few layers to the Q2 API in the past (WebAssembly & a QuakeC interpreter), it's certainly not impossible.. it'd just be a lot of work.

Our game API is mostly stable at this point, I don't think it will be changing between now and release. The only thing I really want to get done is changing our Euler angles over to quaternions, which will obviously break compatibility since the shared entity structure will change, but it's also not a huge priority... and it would make your work a lot harder, heh

[jdolan]

@Raptor007 I completely agree with @Paril 's assessment. A shim between Quetoo and Quake2 is no longer practical, and frankly I don't even think it would be desirable. You'd forfeit much of the benefit of being on a (relatively) modern engine: 40Hz tick, Q3 animation system, client game module, ability to send custom game-defined packets, etc. It would take less effort, and produce a far higher quality result, to actually port Action to Quetoo properly, if that is something that folks want to do.

The point of this ticket is to prove out how someone might do that. I think the question is, do you fork Quetoo altogether, or is there a way to enable mod development with only a subset of the code.

To be honest, I am tempted to say that, in the age of Github and forks and cross-repo pull requests, forking Quetoo might actually be the pragmatic answer. I think you would still copy the "default" game and cgame modules to action and focus your changes there. This would allow you to work in your own subtree but still take updates from upstream, and allow you to cherrypick any "default" mod changes into that subtree as well.

[jdolan]

I think this is the recommendation we should make to any team considering using Quetoo as a mod platform: fork, copy the game and cgame module, and profit. I'm closing this ticket.

[Raptor007]

@jdolan Small nitpick, AQ2 actually does support 40Hz tick using sv_fps 40 in q2pro, but I have no other arguments with your assessment and suggestions. When I first came up with the shim idea (and perhaps got some people's hopes up for Action Quetoo) I thought Quetoo was mostly just going to be a Quake2 client-side facelift. This is clearly not the case, and I'm sure being such a substantial rewrite makes it a better game.

Someday someone could fork Quetoo into Action Quetoo, and I agree that this will yield a much better end result than just making a shim to run the Quake2 mod. I don't have the time for this right now. I would encourage anyone else with some knowledge and drive to take a stab at it.

For those who really want a prettier AQ2 right away, it works great in Q2RTX.

[Paril]

Q2pro's sv_fps does allow for a higher tickrate on the server-side, but it's still 10 hz keyframes; clients can still connect with a 10hz client and "just work", animations still play at 10hz, etc. It's not the same as our actual fully 40hz setup, so you'd still have to deal with the differences there.