The Basics

General File Structure
Available Tags
Complete Example of a .mod File
Limitations

Advanced Rules

Filenames
ID
Version
Mod Info
Author
Homepage

The Basics

General File Structure

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.

Available Tags

Right now, there are 10 different tags available:

Tag Description Multi-line*

<ID> This is the name of the mod No

<Version> Mod version No

<Mod info> Mod description and information like instructions, features, version history and additional credits Yes

<Author> Here you can put your name No

<Homepage> If you have a homepage or emial address, you can put it in here No

<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 lines Yes

<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

Complete Example of a .mod File

Here is an example of a .mod file. Please visit http://boardmod.yabbforum.com/mods.php 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>

Limitations

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.

Advanced Rules

Filenames

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".

ID

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.

Version

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".

Mod Info

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

First you should write a short description of the mod. Make it as informative as possible since people normaly only read the first few lines when browsing through the mod list.
After this description a short list of features is a good thing.
If your mod comes with additional files, make sure to mention this and give instructions on how to install the mod completely (what files to upload where, CHMOD, ASCII or Bin...).
If your mod comes with a readme.txt, mention this uppercase. Some people will miss those information otherwise.
Finally a version history should be there if any.
anything else like additional credits...

Author

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!

Homepage

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> mailto:X_X_L@gmx.net </homepage>

Links

Comments

If you find any misstakes or if you want to comment anything on here, please follow this link or email to at X_X_L@gmx.net

This file is part of BoardMod. Visit http://boardmod.yabbforum.com for more information.