Need sanity check on source modding and the -g option: Inconsistent and incorrect documentation?

ThomasT | 2012-08-19 02:56

I am attempting to understand Sauerbraten's mod development model. First, I have successfully compiled and run the Justice Edition and latest svn release of Sauerbraten as well as Tesseract, all under Mac OS X Snow Leopard. (Compiling and modifying the svn release has some issues on the Mac that I've solved but won't go into here unless someone would like to hear about them.)

Next, I've attempted to understand how source mods are made. I found http://cubeengine.com/forum.php4?action=display_thread&thread_id=1592 ("[MODDING] Your first Sauerbraten MOD, Tutorial 1"). It goes into great detail, describing how to create a new Sauserbraten mod by copying fpsgame, changing the makefile, etc. It then says to specify -g[modname] to execute the mod. However, the Sauerbraten configuration page (http://sauerbraten.org/docs/config.html#_minus_gn) says the -g option is used to specify the maximum number of bots a master can add to a server.

On the third hand, single stepping through the code leads to the argument parser in main() (i.e. SDL_main()) in engine/main.cpp). The parser indicates that the -g option is used to specify the log file! So it looks like the code, configuration documentation, and tutorial all disagree with each other.

Furthermore, after examining the included Makefile it looks like rpggame is not included, in disagreement with the tutorial. I've searched quadropolis for source mods, and it looks like every one at least that I could find just modifies the base source files and distributes the modified files in the mod. I've also done other fairly extensive searches of the web and have found no other information, except maybe a few other pages that say to specify the -g option to execute a mod.

Furthermore, the Mac OS X launcher internally sets the -grpg option to go into the (unused) rpg game code. I hacked the NIB file to actually exercise this path, and not unsurprisingly a log file called "rpg" was created in the user's default directory, sigh, and the rpg game code was never executed.

Lastly, after some more single-step spelunking and code analysis, I see that the game code is specified in the game namespace. This is true for both rpggame and fpsgame. What that means is (obviously) only one or the other but not both can be compiled into the code.

So of course what has happened is the source code has evolved to the point that it is out of sync with some code, documentation, and tutorials. Unfortunately this means it is all but impossible to discern the proper model for source modding the game engine at this point.

So could someone please provide me with some historical perspective on this (since I'm new to the forums)? Also, some guidance as to the proper current way to create and distribute source mods would be appreciated. Thanks in advance for your help!

Rating

points

(0 votes)

Comments

Suicizer | 2012-08-19 10:49

Tutorials and documents are often outdated and sometimes not fully 100% true or missing some side information. I think the best way to get around is to learn a bit from them (like you did) and then explore the rest on your own (or by asking people which know the code well).

ThomasT | 2012-08-19 21:26

Thank you, Suicizer, for the (fast) response. I agree. I also realize my initial post was a bit long. However, I felt I needed to make it clear that I'd done the requisite legwork, but had run into some baffling inconsistencies that forced me to venture into the forums to ask for clarification. I also wanted a good record of what I'd done so that anyone coming afterwards would find this thread through searches. (This is in essence a written history "tribal knowledge" update.)

So then, again to help with that written record, this is what I've found so far:

The current form of the Sauerbraten engine does not allow rpggame and fpsgame to coexist because both are in the same "game" namespace with members with the same names. Attempting to include both in the engine would result in namespace collisions and thus a failure to compile.
The rpggame code is not built by the Mac OS X XCode project, and thus not in the build target. Using that code would require XCode project changes.
Similarly, the included Makefile does not have any references to the rpggame code either. For all intents and purposes it appears all the code in rpggame is defunct.
The Mac OS X nib file directs the play action to explicitly start the fpsgame. The backing Objective-C does have some unused members to deal with "rpg mode", but they don't work because they assume -grpg would cause the rpggame code to be executed which it cannot be. Instead, hacking the nib to use the "rpg mode" code results in an rpg log file created in the user's sauerbraten ApplicationSupport folder, since -g currently specifies the log file name.
The current approach to source modding the Sauerbraten engine is to either:
- modify existing files in place (eg. files in fpsgame), or
- put modified files in a new directory with the same names as in fpsgame and change the build system to exclude the corresponding files in fpsgame and instead include the files in the new directory.
New files should be put in a new subdirectory at the same level as fpsgame, to help segregate them from the existing code.
The source mod is then distributed with a tree structure the same as Sauerbraten's with only new/modified files included. Such a tree can then be overlayed on top of an existing Sauerbraten source distribution. (Note that if files are placed in a new directory, or new files are introduced, then either a new Makefile/Xcode project or explicit instructions on how to update the build system would need to be included with the mod.)
As for larger distributions by way of example:
- Red Eclipse has put the game code in a directory called game instead of fpsgame. The rpggame directory is gone.
- The Intensity Engine has game code in fpsgame, but other (no doubt more specific) game code is in an intensity directory at the same level as fpsgame. Likewise the rpggame directory is gone.

Please, if any of this information is incorrect let me know. Again, thanks for your support!

Suicizer | 2012-08-19 22:21

If I were you, I would ask Eihrul, Quin or Baby-Rabbit about it, as they are 1 of the persons which are the closest to such information. I often not recommend to do so, but in your case you could put this on the official forum of Sauerbraten.org. Contacting them via IRC on irc.quakenet.org in the channel #sauerbraten is also an option.

ThomasT | 2012-08-20 00:41

Thanks for the name references. I'll give them a ring. However, I think I may have accidentally stumbled across the answer I was looking for.

I was searching the cube forums for some unrelated information when I found a thread on Free CC music (http://cubeengine.com/forum.php4?action=display_thread&thread_id=2059). If you follow the link and browse to response #19 by Hiratio Kirata ("Re: Eisenstern - dead?"), it mentions a redesign of the engine from igameclient, igameentities and igameservers to namespaces.

My guess is the game used to have a class hierarchy but it was flattened to plain namespaces, possibly to avoid the performance hit going through virtual members, but probably also to simplify the code. That's the kind of redesign that would nix mod loading. However, I can verify that with Eihrul, Quin, or Baby-Rabbit.

This is important because one of the changes I was considering for my own project was introducing a virtual base class for handling mods, so I need to understand the reasoning behind the conversion to namespaces.

RaZgRiZ | 2012-08-19 22:59

Since you seem to be interested in RPG, why not talk to Hirato about his Platinum Arts Sandbox as well?

Oh, and Intensity is long dead. You should check Octaforge, talk with q66.

ThomasT | 2012-08-20 01:34

Thanks, RaZgRiZ. I'll look into Platinum Arts Sandbox. It's not so much that I'm into RPG. Rather, it's that I'm not into FPS. (I'm interested in exploring other possibilities...) I'm planning on tearing apart the engine to learn how it ticks, and see what I can do with it. I'm currently orienting myself with the general architecture, which prompted my modding question. (You'll note from one of my other responses that I'm already familiarizing myself with asset attribution. Speaking of that...)

Intensity may be long dead, but the engine is under the MIT/X11 license (http://www.syntensity.com/toplevel/intensityengine/). Also, the source distribution has a very permissive license (it's pretty much CC-BY), which makes it much easier to bootstrap a project using its basic assets. Red Eclipse is similar in that it is under CC-BY-SA unless otherwise noted.

The problem with the Sauerbraten source distribution is it has no assets. The problem with the game distribution is that most of the basic assets (the digital fonts used for capture, simple textures for sliders, cursors, etc.) have no attribution, rendering them unusable in a possibly commercial distribution (CC-BY-SA in my case).

What I'm considering doing is putting together a basic mod containing just enough CC-BY-SA assets to get the engine running. I'll scrounge them from other projects such as Red Eclipse, Intensity, etc., plus some things made by myself, also under CC-BY-SA. This would be a "game engine developer starter pack", with very carefully tracked attributions, as well as abundant READMEs to help developers know what to do.

As for Octaforge, I've already got it. One of the other things I've been considering is adding Lua support. (FYI I did the Mac OS X packaging program for Homeworld 2, a game that uses Lua with its assets.)

Suicizer | 2012-08-20 01:42

There are several texture packs and models around here on Quadropolis which are configured to work right away on anything close to Sauerbraten (in the worst case you only have to change their path-directory). The same counts for skyboxes, fonts and other stuff. Even if they wouldn't completely fit your licence preferences, they can always be used as a start of a mod (which you could replace afterwards).

ThomasT | 2012-08-20 02:28

Yes, I've done searches, although I haven't yet examined the licenses in detail. I just think it would be helpful to have something small that provided only the basics so that (a) someone would not have to worry about legal ramifications if an asset leaked out, (b) they would have a good idea of what was actually necessary (i.e. hardcoded into the engine) without having to search the source, and (c) it would make it easier to identify the placeholders.

(Note: In case it isn't clear what I mean by hardcoded, the engine has hardcoded string keys for things like the default font, as well as hardcoded locations for various cfg files in the data tree. Looking at the Sauerbraten distribution for example it isn't clear what in the data tree is absolutely necessary, and what is specific to the Sauerbraten game itself.)

ThomasT | 2012-08-20 03:26

Ah. Platinum Arts Sandbox is only Windows XP/Vista/Win7. There's no linux or Mac OS X, so that knocks that out. Oh well. Thanks anyway RaZgRiZ for the thought. Hmmmm. Now that I see their web site, I think I've been there before... [Note: Too bad I can't edit my previous response. Otherwise I'd just have added this to that.]

Quin | 2012-08-20 08:22

Many years ago, Cube 2 did develop the virtual classes in order to accommodate the secondary RPG game module (which is long since defunct, and only kept in the distribution at the insistence of the creator). I used to use this for "SauerMod" in order to create alternate games with the same binary, and I admit it was fun to play with. The bonus of this is all I needed to do was distribute a binary and any assets I needed for my project specifically, and you would just drop those into an existing Sauerbraten install (drawback being, people *needed* it installed for it to work at all).

I later moved on from modding Sauerbraten in order to create a new game, teamed up with a guy who was working on "Blood Frontier" which ended up being a total conversion. During development on that, I ran into quite a few problems each time I modified a game source file; the virtual igameclient heirarchy required it all be compiled as one object, *every* section of it was a header included in the main fpsgame.cpp - and working on a slower computer at the time, the process of compiling this for one simple change became quite a nuisance (would take me 5 minutes, no matter what I changed).

At some point, we got handed this new UI code which was all contained in this nifty little namespace, but at the time I had no idea what such a thing was, so as always I researched it and was struck with a "light bulb" moment. I quickly came to grips with the concept and converted Blood Frontier's codebase from classes to namespaces, allowing me to separate each part of the game code into their own source files and compile them individually. This sparked some conversation with eihrul, and he eventually took the idea and made it universal (so now Cube 2 uses the same idea, slightly modified). This opened up opportunities for eihrul to further optimise the compilation process, and not long after he made the important headers precompiled.

The idea now is that if you're making mods, you create your own binary for each game type you're after. You can either replace fpsgame with your own code, or create a new subdirectory for your code. It may sound like a step backward in some ways (there is duplicate code in each binary you generate), but it has made the compilation process a whole lot more pleasant.

After a disagreement with the creator of Blood Frontier, I decided to fork off and create Red Eclipse. With this I had a new focus intended to address some of the problems I had witnessed or hit my head up against in the Cube Engine community; the most important of which was the lack of open source or properly attributed assets. So yes, you are quite free to take almost any part of Red Eclipse and use it in your own projects (the exception being our name, logo, etc). I realise that the project may not be minimal enough for most people just starting out with the engine, but I do provide a lot of nifty things you won't see in Cube 2 (and, after all, I'm making a game, not an engine).

Your posts have reassured me that the choice to drop the Mac OSX launcher in Red Eclipse and have the game behave as it does on every other platform was a good idea. I can't believe that the Sauerbraten launcher still hasn't received any updates, and it is quickly suffering from a lack of proper support. I am not strictly a Mac OSX developer myself, but I did buy one to facilitate targeting the platform for Red Eclipse and have learned enough (and a few tricks as well) to get me by.

Contrary to what Suicizer has said, I do not recommend contacting any of the other developers he has mentioned (except maybe Hirato), as we don't usually entertain such long winded explanations to new members of the community. Mostly due to historical evidence about amount of effort versus the likelihood of you contributing something useful back, but also that the Cube 2 source code is provided on an "as-is" basis, and it is up to the individual to learn how to use it.

ThomasT | 2012-08-21 03:17

Thank you, Quin, for the detailed response. The explanation of the reasoning behind eliminating the class structure was most constructive, and thought-provoking. Indeed, if one is supplying plugin capability, it really must be done dynamically rather than be compiler-driven. However, even doing it dynamically is much less important than providing additional scripting capability. Supporting binary plugins should be isolated to corner cases, and that corner should be made as small as possible because injecting the execution of foreign code into the binary is always a risky proposition.

My abundant thanks for your work on Red Eclipse. (Unfortunately at the moment it is DOA for me. It compiles but at startup dies in the dynamic loader with a NULL dereference. Very strange. I'm still looking into the issue.) Your diligence at securing proper attributions (and making those such that the resources could be used, even commercially) is to be applauded.

Also, eliminating the Mac loader was absolutely the right call. (Honestly I wondered why it existed in the first place. It seemed unnecessary.) Another outstanding issue with it is that in-game resolution settings are not reflected in the loader. Since I'm ramping up Mac OS X development, I wonder if the devs would be open to some help there, especially if the plan was to get rid of it? It shouldn't be too hard to follow Red Eclipse's model.

Note that I did get a response from Eirhul on irc, although his comment was significantly shorter than yours. (The reason -g was eliminated is because it was stupid, and for mods, compile different games into different bins.)

As for contributions, my hope is that I'll be able to. We'll see how this goes.

Again, thanks for taking the time to recount the history.