1. We have added a Gift Upgrades feature that allows you to gift an account upgrade to another member, just in time for the holiday season. You can see the gift option when going to the Account Upgrades screen, or on any user profile screen.
    Dismiss Notice

Mod contributions guide

Discussion in 'Civ4 - Community Enchancement Project' started by The Great Apple, Apr 17, 2006.

  1. The Great Apple

    The Great Apple Big Cheese

    Joined:
    Mar 24, 2002
    Messages:
    3,361
    Location:
    Oxford, England
    Firstly, this is a draft. It will almost certainly get improved later when people apart from myself can actually access this forum.

    Aims:
    The main aim of this project is to improve Civ 4 as a game without altering the default game that the user sees at all (unless they want it to be altered). I've split possible changes up into 6 sections.

    1) AI
    2) UI
    3) Performance
    4) Modablilty
    5) Bug Fixes
    6) Gameplay Tweaks

    Guidelines are as follows:

    1) AI - the AI changes must make the AI better than the current release version of the mod without significantly degrading game performance. The AI should not cheat in any way, and ideally treat the human as any other AI (although the default AI has some code which recognises the human...)

    2) UI - it could be more information, or better displaying of imformation. Try to keep to Civ 4 styles of tooltips and menu selection, and don't overdo the clutter. Also, while customisable items are good, make sure you don't include too many, as it would be very easy for it to get out of hand.

    3) Performance - this could be tiny optimisations in the code, or masive re-writings of functions. All I ask is that your code runs faster than the code it replaces, and that it does exactly the same thing as the code it replaces.

    4) Moddability - make sure that the added modding feature is easy to understand, as well as potentially useful. Too many added features will slow the game, as well as make existing features more complicated to use. These features should have no effect unless activated by a modder.

    5) Bug Fixes - fixing silly little glitches. Please make sure that the bug is a bug, and not a feature before you go and kill it.

    6) Gameplay Tweaks - these should always have an enable/disable switch in the CCP options tab and should be disabled by default. If you want to add a gameplay tweak to the mod I suggest you make a thread explaining what you are tweaking, and why you are tweaking it. If the community as a whole decides that it would be a good option to have, then feel free to go for it. Please bear in mind that we don't want too many options, or it will be confusing to the user, and very hard to code an AI to take into account all the different options.

    These guidelines are by no means definative. You may think that your code meets them, others may not. Even if it doesn't, it might still be included if enough people thing that it should be. It might be an idea to make a post saying what you plan on doing before you launch into it, just in case.


    Summissions:
    To sumbit a change please post the changed files in this forum, as well as a brief explaination of what your changes do, and why. The changes must be clearly commented, and you must have tested them to make sure that they do work, and do have the results that you think they will have. It would be nice if you could also try and code in the style set out by Firaxis, although this isn't essential.

    The entire source-code for the mod will be available for download both in the sticky on this forum, as well as on SourceForge, and our own server. I suggest you test your changes with this version rather than the default version, as it may conflict with current mods.


    Backward Compatabilty:
    Ideally, we want every revision of this mod to be backwardly compatable with the previous version. While this will not be possible with all mods, can I ask that when modding you take this into account. If you can't avoid it, then please do NOT upload your mod immediately. Instead, if you wait until it is announced that the next version of the mod will break backward compatabilty, and then add your code.


    Commenting Style:
    The general commenting style for the mod is as follows. It would help alot when editing code if everybody could stick to these guildlines. While some parts are optional, I suggest you include them as it will make any future edits of your code by yourself, or anybody else easier.

    • 1) Header: All mod changes are listed in one log file. This file contains the mod name (brief), the author name, the mod version, the release date of the mod, and the files which the mod edits.
    • 2) Types of changes -
      • a) Single line changes:
        Format:
        <code> /* Mod Name | Author Name | Mod version of update (optional) | Comment (optional) | Date changed (optional)*/

        For example:
        Code:
        doAITalk(i); /* TalkingAI | TGA | v1.1 | Calls the talking function | 26 March 06 */ 
      • b) New functions:
        Format:
        /* Mod Name | Author Name | Mod version of update (optional) | Comment (optional) | Date changed (optional) */
        <code>

        For example:
        Code:
        /* TalkingAI | TGA | v1.1 | Works out what the AI says | 26 March 06 */
        void doAITalk(int iTalkType)
        {
            if (iTalkType == 1)
            {
                AISay("You fight like a dairy farmer");
            }
        }
        
      • c) - Editted functions:
        Format:
        /* START -- Mod Name | Author Name | Mod version of update (optional) | Comment (optional) | Date changed (optional) */
        <code>
        /* END -- Mod Name | Author Name | Mod version of update (optional)*/

        If code is being replaced, then it should be left commented out so that it can be easily reverted. This code should be within the change brackets so that it can be easily seen.

        For example:
        Code:
            <code>
        /* START -- TalkingAI | TGA | v1.0 | Makes the AI say 'hi' if you are at war with him | 26 March 06 */
            if (bLandWar)
            {
                AISay("Hi");
            }
        /* END -- TalkingAI | TGA | v1.0 */
            <code>
        

      Dates should not be in a format which can be easily confused. dd/mm/yy and mm/dd/yy are not acceptable, as they can be easily misread.

      Personally I prefer editted code comments to be completely untabbed so that they can be spotted more easily when combining. I supose it doesn't really matter.


    NOTE: If you want your code compatable with a global disable/enalble switch which can be accessed in game please include this format with your changes:
    Code:
    if (bCppEnabled == true)
    {new function}
    else
    {old function}
    
    You probably don't have to do it if you're just making a performance tweak, but if you're altering game behaviour it would be nice...
     
  2. 12monkeys

    12monkeys Chieftain

    Joined:
    Nov 24, 2003
    Messages:
    440
    Location:
    Germany, Europe
    Maybe its good to have a member list somewhere. Because this forum is hidden actually, nobody knows who is able to read the stuff posted here. We may also create a thread where new members do a little presentation of themselves with name, major skills, minor skills , the things he wants to contribute to the project and a way to contact him (mail, PM, whatever).
     
  3. The Great Apple

    The Great Apple Big Cheese

    Joined:
    Mar 24, 2002
    Messages:
    3,361
    Location:
    Oxford, England
    I've kinda done that with the "Mods in progress" thread. I might re-vamp it a bit though to be more in this style.
     
  4. Belizan

    Belizan Chieftain

    Joined:
    Jan 11, 2006
    Messages:
    1,060
    You want us to post little personal introductions in the mods in progress thread?
     
  5. Chalid

    Chalid Black Dragon

    Joined:
    Nov 24, 2005
    Messages:
    1,742
    Location:
    Munich, Germany
    How about a common commenting syntax?

    Further we could set up a reference page via doxygen if someone has webspace available for this.
     
  6. The Great Apple

    The Great Apple Big Cheese

    Joined:
    Mar 24, 2002
    Messages:
    3,361
    Location:
    Oxford, England
    At the moment I'm using //TGA -- Start and //TGA -- End to show the start and end's of the changes I've made. I could easily change if others want to do it a different way though.

    Thoughts?
     
  7. Chalid

    Chalid Black Dragon

    Joined:
    Nov 24, 2005
    Messages:
    1,742
    Location:
    Munich, Germany
    For new function i would like something like:

    Code:
    /*! \brief Brief-Description 
     *
     * Description
     * 
     * \author Chalid
     * \ingroup EnhancedPromotions
    */
    
    At the beginning of each new function
    I'm not sure if the /ingroup sytnax is correct for marking parts of a module but this can be looked up..

    Simpler changes we could simply mark with
    Code:
    /*Author: Chalid, BelongsTo: EnhancedPromotions */
    
    Either way, the Modification where a change belongs to must be marked, too.

    Oh and I prefer /* */ to // as it looks like brackets and i know some complilers that don't interpret // .... actually i have to use one of those at work...
     
  8. The Great Apple

    The Great Apple Big Cheese

    Joined:
    Mar 24, 2002
    Messages:
    3,361
    Location:
    Oxford, England
    Updated the AI guidelines about cheating... thought I'd make sure!

    Oh, and commenting. Seems to me we kinda need a commen commenting convention. There have been lots of suggestions, but to be honest I'm far from the best person to decide between them - it seems most of you work in the field, and so have a little bit more experience than me in such matters.
     
  9. The Great Apple

    The Great Apple Big Cheese

    Joined:
    Mar 24, 2002
    Messages:
    3,361
    Location:
    Oxford, England
    Right, I've updated the commenting as well as adding a new "Bug Fixes" section.
     
  10. 12monkeys

    12monkeys Chieftain

    Joined:
    Nov 24, 2003
    Messages:
    440
    Location:
    Germany, Europe
    One thing to be changed :

    the end tag of the comments must have a version number to. If you do changes you need to know, to where the end tag belongs to.

    So change

    /* END -- TalkingAI | TGA */

    into

    /* END -- TalkingAI | TGA | v1.0 */


    12m
     
  11. The Great Apple

    The Great Apple Big Cheese

    Joined:
    Mar 24, 2002
    Messages:
    3,361
    Location:
    Oxford, England
    I've added a bit about gameplay tweaks having noticed Impalers idea for a new GP system. Does everybody agree that there is a place for this kind of mod in the project?

    This poses a slight problem however. Who decides if a particular change is good, or whether it is just useless additional clutter? It seems quite a distant problem at this early stage, but I think we need to set something in place reasonably shortly or it may be too late.

    I've suggested in the first post that each gameplay tweaking mod should have a thread made about it, and then discussed to make sure that people want it. It's quite hard to define whether a particualar mod should make it or not based on the replies of a thread though, so maybe there should be some sort of veto system where if a main contributor to the project thinks that it is a bad idea, and can't be convinced otherwise, then it doesn't get in.

    Thoughts?
     
  12. Gerikes

    Gerikes User of Run-on Sentences.

    Joined:
    Jul 26, 2005
    Messages:
    1,753
    Location:
    Massachusetts
    First off, hello all! I'm looking forward to doing some work with you all.

    On to the topic at hand...


    I agree. At the very least, there need to be an enable / disable that defaults to disabled, like you've already said, but I think the phrase "an enable / disable switch" needs to be clarified. I'd like to also see an easy way for these to be enabled by anyone using the project for their mod. For example, if someone wanted to use this GP tweak in their mod, they could enable or disable it in an XML file, so that they don't have to do too much to have it enabled by default in their mod. By default, the XML file just have all tweaks disabled.

    At the same time, making a new DOMAIN type (such as a floating domain unit, traveling over water and land), if acceptable as a mod contribution, has already achieved the required "have an enable / disable that is disabled by default" simply because no unit in the XML has that domain type, and thus no change would be made to a typical game of Civ4. It would seem silly to have an enable / disable in the XML files, since enabling this would consist of just making the unit of that domain, which a person would have to do anyway.

    While defining what is and isn't a gameplay tweak might be tough, defining exactly what enabled and disabled is is probably easier.

    Do you also think that it's wise to have this same tweak enabling/disabling put into an option tab window so that the tweak can be changed real-time, if possible? This too could be considered an enable/disable switch, and would require replacing two python files

    1.) entrypoints/CvOptionsScreenCallbackInterface.py
    2.) screens/CvOptionsScreen.py

    Finally, in terms of overall acceptance into the SDK, I think there should either be started a thread where you add what gameplay-tweak mod you're thinking of adding and discussion takes place on it, or a new thread for each tweak. In either case, responses can be made to it, and if someone finds troubling the aspect of including it in the mod, either a vote can be taken or something of that matter.
     
  13. The Great Apple

    The Great Apple Big Cheese

    Joined:
    Mar 24, 2002
    Messages:
    3,361
    Location:
    Oxford, England
    SimCutie has already done the in-game options menu, which should be going out in the first version. I think almost all the Gameplay tweaks should be available here. Anything that has to be enabled using the XML is really increased moddablilty, rather than a gameplay tweak.

    I've fiddled with the wording - hopefully it's a bit clearer now.
     
  14. chrusion

    chrusion Chieftain

    Joined:
    May 5, 2006
    Messages:
    36
    Location:
    Seattle, WA
    I believ that mod game tweaks that are player switchable should be able to be permanently turned on or off by the mod designer. Some mod gameplay may require the tweak to exist or not exist for the mod to function as designed.
     
  15. The Great Apple

    The Great Apple Big Cheese

    Joined:
    Mar 24, 2002
    Messages:
    3,361
    Location:
    Oxford, England
    As the code for the options menu will be in python this should be possible for them to do by themselves. They'd just have to remove the option there.
     

Share This Page