How To Write Mod Files 
Ver 1.0.1 from 1. Sept 2002, written by Michael Prager

The Basics

  1. General File Structure
  2. Available Tags
  3. Complete Example of a .mod File
  4. Limitations

Advanced Rules

  1. Filenames
  2. ID
  3. Version
  4. Mod Info
  5. Author
  6. Homepage

Links

  1. Comments


The Basics

  1. General File Structure

    2. Before we look into the rules of mod writing, we first have to get an idea of what a mod is. In general a mod is nothing else than instructions like "look for this text line(s) in file X" and "replace it with this text line(s)" stored in a single ASCII text file. Mod files have the extension ".mod" and can have any name. The file format looks like HTML or XML (but it is NOT equal). You have several "tags" available which can surround something, just like brackets.

    Example

    <Mod info>
    This is a test and does nothing
    </Mod info>

    However there is a big difference to XML and HTML: You are not allowed to write tags like this:

    This does not work:

    <Mod info>This is a test and does nothing</Mod info>

    You have to put a linebreak after and before each tag!

    Another thing you have to know is that some tags only allow one line! Please see the tag list for which tags are "multi-line" and which are not.

    back to top

  2. Available Tags

    3. Right now, there are 10 different tags available:

    TagDescriptionMulti-line*
    <ID>This is the name of the modNo
    <Version>Mod versionNo
    <Mod info>Mod description and information like instructions, features, version history and additional creditsYes
    <Author>Here you can put your nameNo
    <Homepage>If you have a homepage or emial address, you can put it in hereNo
    <Edit file>Specifies a file which will be modified. The file path is always relative to the main script file (e.g. YaBB.pl)"No
    <Search for>One or more lines to search for in the file specified before with <Edit file>Yes
    <Replace>Replaces the line/lines specified by <Search for> by one or more other linesYes
    <Add before>Adds one or more lines before those which had been searched by <Search for>Yes
    <Add after>Adds one or more lines after those which had been searched by <Search for>Yes
    * Only tags which are "multi-line" allow more than one line

    back to top

  3. Complete Example of a .mod File

    4. Here is an example of a .mod file. Please visit mods.boardmod.org for more examples.

    <ID>
    Example Mod
    </ID>

    <version>
    0.1 Alpha
    </version>

    <Mod info>
    This is an example mod to demonstrate the possibilities
    of the mod format. Please note that this mod is NOT made to
    be applied to anything. It's just an example!
    </Mod info>

    <author>
    Mr.X
    </author>

    <homepage>
    http://www.mr_x.com
    </homepage>

    <Edit file>
    Sources\Display.pl
    </Edit file>

    <Search for>
           if($signature ne "") {
                   $signature = "<br>-----------------<br>$signature";
                   }
    </Search for>

    <Replace>
           if($memset[5] eq "\n"){
           $signature= "";
           } else {
           $signature= "<hr size=1 noshade width=40\% align=left>$signature";
           }
    </Replace>

    <Search for>
           $signature= "<hr size=1 noshade width=40\% align=left>$signature";
    </Search for>

    <Add before>
           #Example modification
    </Add before>

    //////////////////////////////////////////////////////
    Outside the brackets you can write what you want! The BoardMod will ignore these lines...
    \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

    <Edit file>
    Sources\ModifyMessage.pl
    </Edit file>

    <Search for>
           print FILE "$subject\|$mname[$x]\|$memail[$x]\|$date\|$musername[$x]\|$icon\|0\|$ENV{REMOTE_ADDR}\|$message\n";
    </Search for>

    <Add after>
           $dpmsgs[$dpmsgsc] = "$dpthreadb|$dpsub|$dprn|$dpem|$date|$dprc|$dpun|$dpic|$dpuk\n";
           open(TN, ">$boardsdir/$currentboard.txt");
           &lock(TN);
    </Add after>

    back to top

  4. Limitations

    5. Currently there is a very important limitation you have to know about: It is only possible to search for complete lines, not for single words! Always keep this in mind when writing your mods. This is very important when you want to search for some lines which start with spaces or tabs. Leaving them out in the <search for> tag will make your mod not working.

    Example

    <search for>
    for i := 1 to 10 do begin
      b := b * z + 1;
    </search for>

    is NOT equal to

    <search for>
          for i := 1 to 10 do begin
            b * z + 1;
    </search for>

    Another limitation is that empty <replace> tags are not allowed. So for example the code to remove a line does not look like this:

    This does not work

    <replace>
    </replace>

    or

    <replace>

    </replace>

    Instead use this code

    <search for>
    i := i * i + 1;
    i := i - 1;
    </search for>

    <replace>
    i := i * i + 1;
    </replace>

    The reason for this limitation is to keep all steps "undoable". This is required to provide uninstall ability.

    back to top



Advanced Rules

  1. Filenames

    2. The .mod filename should be equal to the mod name (<id> tag) to prevent confusion and to make sure that the filename is unique. In addition there are some additional standarts we use for our mods at YaBB to keep everything "uniform": spaces are replaced by "_" (underscore). If the mod version is not 1.0 then the version should be added to the filename too but without the dots. Do this to avoid problems when people have multiple versions of the mod in the same folder. Look at the example to get an idea of it.

    Example

    If the modname is "The Great Mod" and its version is "2.55a" then the filename would be "the_great_mod_255a.mod".

    If you compress your mod as a .zip file (e.g. if your mod comes with some additional files), you should give your .zip file the same name as the .mod file.

    Example

    If you pack "the_great_mod_255a.mod", the .zip name would be "the_great_mod_255a.zip".

    back to top

  2. ID

    3. This is a very important tag, its content will be used in the mod database and people have to identify the mod by this name so please pay attention to it. The general rules are:
    Keep the name short but not too short, using up to 5 words is fine. Please give the mod a descriptive name! Names like "MEGA Super Mod by www.xy.com!!!" won't help anyone.

    back to top

  3. Version

    4. Normaly a version number has a structure like "1.0.1.2" but you are very free here. For example you could use "1.0", "2.55b" or even "beta1".

    back to top

  4. Mod Info

    5. This is THE tag so take yourself some time on this one.

    back to top

  5. Author

    6. Don't forget that this tag does only support one line so only use one. If there are multiple authors then list them with commas. If you release a new version of a mod which you did not originally create, please leave the author tag alone and put your your stuff at the end of the description tag (<Mod info>) instead.

    BTW: Never release a new version of a mod which you did not originally create, ask the original author first. Otherwise you may violate his copyright!

    back to top

  6. Homepage

    7. Same thing as with the <author> tag: only one line is supported. Leave the author's original address in there and put yours in the description if you are not the original author. Don't use commas here since BoardMod will use this as link.

    Tip: You can also put your email address in here if you don't have a webpage.

    Example

    <homepage>

    </homepage>

    back to top



Links

  1. Comments

    2. If you find any misstakes or if you want to comment anything on here, please follow this link or email to

    back to top


This file is part of BoardMod. Visit http://www.boardmod.org for more information.