1. We have added the ability to collapse/expand forum categories and widgets on forum home.
    Dismiss Notice
  2. Photobucket has changed its policy concerning hotlinking images and now requires an account with a $399.00 annual fee to allow hotlink. More information is available at: this link.
    Dismiss Notice
  3. All Civ avatars are brought back and available for selection in the Avatar Gallery! There are 945 avatars total.
    Dismiss Notice
  4. To make the site more secure, we have installed SSL certificates and enabled HTTPS for both the main site and forums.
    Dismiss Notice
  5. Civ6 is released! Order now! (Amazon US | Amazon UK | Amazon CA | Amazon DE | Amazon FR)
    Dismiss Notice
  6. Dismiss Notice
  7. Forum account upgrades are available for ad-free browsing.
    Dismiss Notice

[Tutorial] Modding with BUG

Discussion in 'Civ4 - BTS Unaltered Gameplay (BUG, BAT and BULL)' started by EmperorFool, Jan 31, 2010.

  1. EmperorFool

    EmperorFool Chieftain

    Joined:
    Mar 2, 2007
    Messages:
    9,633
    Location:
    Mountain View, California
    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.

    Please do not post questions about BUG in general or ask how to merge a mod in this thread. Post only questions or comments directly related to the tutorial itself.

    • 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.
     
  2. EmperorFool

    EmperorFool Chieftain

    Joined:
    Mar 2, 2007
    Messages:
    9,633
    Location:
    Mountain View, California
  3. Afforess

    Afforess The White Wizard

    Joined:
    Jul 31, 2007
    Messages:
    12,239
    Location:
    Austin, Texas
    A brief tutorial on how the BUG panel tabs work would be nice.
     
  4. EmperorFool

    EmperorFool Chieftain

    Joined:
    Mar 2, 2007
    Messages:
    9,633
    Location:
    Mountain View, California
    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.
     
  5. EmperorFool

    EmperorFool Chieftain

    Joined:
    Mar 2, 2007
    Messages:
    9,633
    Location:
    Mountain View, California
    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! :goodjob:
     
  6. Afforess

    Afforess The White Wizard

    Joined:
    Jul 31, 2007
    Messages:
    12,239
    Location:
    Austin, Texas
    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.
     
  7. EmperorFool

    EmperorFool Chieftain

    Joined:
    Mar 2, 2007
    Messages:
    9,633
    Location:
    Mountain View, California
    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.
     
  8. Afforess

    Afforess The White Wizard

    Joined:
    Jul 31, 2007
    Messages:
    12,239
    Location:
    Austin, Texas
    You mean this documentation? Not exactly light reading. It explains everything okay, but assumes you already understand what you are doing. :lol: (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?
     
  9. EmperorFool

    EmperorFool Chieftain

    Joined:
    Mar 2, 2007
    Messages:
    9,633
    Location:
    Mountain View, California
    :lol: 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).

    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.
     
  10. EmperorFool

    EmperorFool Chieftain

    Joined:
    Mar 2, 2007
    Messages:
    9,633
    Location:
    Mountain View, California
    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
     
  11. DaddyHolby

    DaddyHolby Chieftain

    Joined:
    Feb 20, 2003
    Messages:
    32
    Location:
    Superior, Co
    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.
     
  12. Lemon Merchant

    Lemon Merchant Smarticus Pantsidae

    Joined:
    Jun 27, 2008
    Messages:
    4,380
    Gender:
    Female
    Location:
    Red Sector A
    Currently devouring the tutorial. Very easy to understand. Even for me. :)
     
  13. ruff_hi

    ruff_hi Live 4ever! Or die trying

    Joined:
    Oct 24, 2005
    Messages:
    8,882
    Location:
    an Aussie in Boston
    Looked at 2 pages - very very nice. You should include the tutorial in the index panel on the left.
     
  14. DaddyHolby

    DaddyHolby Chieftain

    Joined:
    Feb 20, 2003
    Messages:
    32
    Location:
    Superior, Co
    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.
     
  15. EmperorFool

    EmperorFool Chieftain

    Joined:
    Mar 2, 2007
    Messages:
    9,633
    Location:
    Mountain View, California
    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.
     
  16. DaddyHolby

    DaddyHolby Chieftain

    Joined:
    Feb 20, 2003
    Messages:
    32
    Location:
    Superior, Co
    Here's the error message from the PythonDbg.log file:

    Code:
    08:12:50 DEBUG: BugConfig - loading mod file Lucky Charms
    08:12:50 DEBUG: BugInit - loading mod Lucky Charms...
    08:12:50 INFO : BugCore - creating uninitialized mod LuckyCharms
    08:12:50 DEBUG: BugOptions - getLuckyCharms will return IniFile LuckyCharms
    08:12:50 DEBUG: BugOptions - added option <LuckyCharms__Enabled boolean [True]>
    08:12:50 DEBUG: BugOptions - added option <LuckyCharms__Leprechaun string [Larry]>
    08:12:50 DEBUG: BugOptions - added option <LuckyCharms__MessageColor color [COLOR_YELLOW] list (0 colors)>
    08:12:50 DEBUG: BugOptions - added option <LuckyCharms__FreeGoldAmount int [10] list (5 ints)>
    08:12:50 DEBUG: BugOptions - added option <LuckyCharms__FreeGoldChance int [50] list (11 ints)>
    08:12:50 DEBUG: BUG: looking up LuckyCharms.onBeginPlayerTurn
    load_module LuckyCharms
    
    LuckyCharms
     
    import failed
    
    08:12:50 TRACE: BugConfig - failure parsing C:\Users\Colby\Documents\My Games\Beyond the Sword\CustomAssets\Config\Lucky Charms.xml at line 20
    08:12:50 TRACE: No such module 'LuckyCharms'
    08:12:50 DEBUG: Timer - load mod [Lucky Charms] took 71 ms
    08:12:50 DEBUG: Timer - load mod [init] took 748 ms
    08:12:50 DEBUG: Timer - BUG init [read configs] took 748 ms
    
    And here's the one from the PythonErr.log:

    Code:
    ConfigError: No such module 'LuckyCharms'
    
    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.
     
  17. DaddyHolby

    DaddyHolby Chieftain

    Joined:
    Feb 20, 2003
    Messages:
    32
    Location:
    Superior, Co
    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?
     
  18. EmperorFool

    EmperorFool Chieftain

    Joined:
    Mar 2, 2007
    Messages:
    9,633
    Location:
    Mountain View, California
    Thanks, I fixed the tutorial. :goodjob: I also added a note to make sure someone doesn't put a space in it like I did. ;)

    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.

    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.

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

    Afforess The White Wizard

    Joined:
    Jul 31, 2007
    Messages:
    12,239
    Location:
    Austin, Texas
    Any chance of finishing this tutorial, now that BUG 4.3 is out?
     
  20. Cybah

    Cybah Chieftain

    Joined:
    Jun 22, 2007
    Messages:
    1,479
    nevermind, have to check something.......
     

Share This Page