[Tutorial] Modding with BUG

I am writing a basic tutorial to introduce modders to the BUG Core. This thread is for suggestions for, questions about, and discussion of the tutorial.

• Having trouble getting the code in the tutorial to work? Post here
• Have a question about something the tutorial says? Post here
• Have a suggestion for a new section to add to the tutorial? Post here

For anything else use the appropriate existing thread or start a new one.

Finished Sections

• Getting Started
• Configuration
• Events
• GameUtils
• Options
• Saving Options
• List Options
• Complete Code

Future Sections

• Responding to Changed Options
• Initialization
• Translation
• Options Screen

A brief tutorial on how the BUG panel tabs work would be nice.

Afforess said:

A brief tutorial on how the BUG panel tabs work would be nice.

Click to expand...

You mean for putting your own options on the BUG Options screen? Yes, that'll come after the next few pages. Honestly, though, the best way to do it is to copy a tab/control that works just like you want it to. If you have a specific question about how to use a control, start a thread so we can discuss it and it'll help me get the tutorial started.

I've added the section on GameUtils which should hopefully help a few modders working on them right now. Events and Options are already (mostly) complete.

Next up: Responding to Option Changes, Initialization, Translation, and Options Screen.

I would really love some feedback from the community. I need to know if I'm hitting the sweet spot between too basic (not useful enough for the real world) and too hardcore (useful to only 1% of the modders). I'm also seeing that the documentation pages themselves are a bit out of date and not as detailed as they should be.

Please help me make these pages useful for you and your fellow modders!

At the risk of seeming over-represented:

I read through the entire tutorial, at least what is posted. It's very useful and really good at explaining what is going on. It's a good kick-start to those of us (myself, mainly) who had ideas about setting up some BUG-specific features, but didn't feel like reverse engineering everything.

Out of curiosity, had you read the BUG Core documentation and found it lacking or too technical? In writing this tutorial I have revisited the technical documentation and see many gaps, but the more important thing I think is that it dumps everything on you at once, making it difficult to get started.

EmperorFool said:

Out of curiosity, had you read the BUG Core documentation and found it lacking or too technical? In writing this tutorial I have revisited the technical documentation and see many gaps, but the more important thing I think is that it dumps everything on you at once, making it difficult to get started.

Click to expand...

You mean this documentation? Not exactly light reading. It explains everything okay, but assumes you already understand what you are doing. (Usually the opposite is true for me.) The tutorial layout was a breath of fresh air compared to that.

One thing that would be nice is some concise documentation on all the events in BTS, along with the extra events BULL has added. I had to go open BTS's CvEventManager up to figure out what was what when I needed to know.

I'm fairly familiar with the SDK now, (look ma, no open help threads! ) but it doesn't always translate to understanding python right away. I kinda learned civ modding backwards, eh?

Afforess said:

You mean this documentation?

Click to expand...

That's the XML reference--useful only once you've learned how to use the basic elements and want to look up something you forgot (is an attribute required?) or learn something new (module attribute can be moved to <mod> element so you don't need to repeat it on every element in the file). It is decidedly not good for learning a new concept. I was referring to the page on events and the others listed in the Modders' Corner (the start page for all things BUG-modding).

Afforess said:

One thing that would be nice is some concise documentation on all the events in BTS, along with the extra events BULL has added.

Click to expand...

The events page I linked above lists the events added by BUG and BULL, but it doesn't show the arguments they receive. For those it's best to go to the source (BugEventManager). While a page listing all the BTS/BUG/BULL events with arguments and descriptive text would be very helpful, that information is available in the source, and so I would prefer to spend my time writing documentation not available elsewhere. I think the Civ4 modiki would be a great place for someone to write up such a document.

I have added a page containing the complete tutorial source code as it stands at the end of the tutorial. I will update that page as I add sections.

I really need a better (and shorter) phrase than "Responding to Changed Options". This section will cover functions that get called when an option's value changes. Suggestions?

• Option Change Events
• Option Change Notification
• Detecting Changed Options

EmperorFool said:

I would really love some feedback from the community.

Click to expand...

EmperorFool this tutorial is really good. I've been blundering around for the last month or so trying to add some things and failing miserably. I had looked through the documentation before and found it hard to use for all the same reasons you guys have already stated.

Thanks, this is extremely helpful.

Currently devouring the tutorial. Very easy to understand. Even for me.

Looked at 2 pages - very very nice. You should include the tutorial in the index panel on the left.

Is anyone having any problem with this tutorial? I tried writing the code myself in steps just like the tutorial and every time I tried to load it I got an error thrown by civ saying BUG failed to parse the event tag in the XML.

I've even just grabbed the completed code at the end of the tutorial and tried it and got the same error (when run the finished code throughs an error saying it can't parse line 20 of the Lucky Charms.xml which is the line with the event tag).

I'm using BUG 4.2 and BULL 1.0.

Can you please copy-n-paste the error from PythonErr.log or the TRACE from PythonDbg.log here? It's much easier to help when I can see the exact error verbatim.

Here's the error message from the PythonDbg.log file:


And here's the one from the PythonErr.log:


After looking at these logs I found the problem. I named the Lucky Charms python file "Lucky Charms.py" like it says in the Completed Code section of the tutorial. It should be "LuckyCharms.py" like it says in the Events section of the tutorial.

Sorry about that, I think I got confused when looking at both sections.

Quick question, what's the difference between using class for event-handlers and using module-level handlers?

Is one better than the other? When should you use one over the other? And what is the differences (if any) to the config xml file?

DaddyHolby said:

I named the Lucky Charms python file "Lucky Charms.py" like it says in the Completed Code section of the tutorial.

Click to expand...

Thanks, I fixed the tutorial. I also added a note to make sure someone doesn't put a space in it like I did.

DaddyHolby said:

What's the difference between using class for event-handlers and using module-level handlers?

Click to expand...

When using module-level handlers you must use one <event> element in the configuration XML for each handler. When using a class, you must call addHandler() for each handler in the class's __init__() Python function.

I am planning to have BUG auto-detect your handlers for both methods; I just need to figure out how to handle backward-compatibility so that BUG doesn't register each handler twice.

DaddyHolby said:

Is one better than the other?

Click to expand...

I prefer module-level for a few reasons. First, it's less typing and easier to code since you don't need a class. Second, I like to see the events that a mod requires in the configuration XML rather than buried in the Python. If you're looking at the Python you can already read the function names to see which events it uses.

Third, and most important, it's easier for mods to work together if classes aren't involved. It's really not hard to use classes, but it's just easier to skip them in this case. You can have mod A call out to mod B to have it do something without needing to provide a function to get track and make the class's object available.

However, my preference is far from overwhelming. I would advise you to go with what you understand better.

Normally I would use a class when I needed to initialize data in a single __init__() function that couldn't be done when the module was first imported. However, I added <init> for just this purpose: a function that gets called once after BUG initializes itself. This gives you the same benefit as __init__() but at the module level.

DaddyHolby said:

And what is the differences (if any) to the config xml file?

Click to expand...

Many <event>s (and maybe an <init>) versus a single <events>.

Any chance of finishing this tutorial, now that BUG 4.3 is out?

nevermind, have to check something.......