View source for Help:Adding a format

''This page isn't complete and could definitely be improved. Make changes yourself, or suggest them on the [[Talk:Adding a Format|talk page]]. The [[GRAFTemplate1 Help]] page could also use a lot of work, feel free to make changes or add information.''

== Introduction ==
<div style="float:right;margin-left:10px;background-color:#EEEEEE;border:solid black 1px;width:20%;padding:10px">
<font size="+2">FAQ</font><br>
<br>
'''What about multiple versions of the same game?'''<br>
If a format you are adding is used by multiple versions of the same game (for instance, the PC version and the XBox version, or the demo and the full version), list each version as its own entry in the list of GRAFS and link them all to the same format page. You must also list them seperately in the 'Games' section of that format page.<br>
</div>
Adding a format to the Xentax WIKI is a very easy process. The aim of this tutorial is to walk you through it, step-by-step. You may use the Table of Contents (above) to skip directly to a section, or just read the whole thing through.

=== Naming the Page ===
First and foremost, make sure the format you want to add isn't already on the WIKI. You can do this by [[Special:Search|searching]] for the game's title or any strings in the format (for instance, header strings) and examining any results that come up. If your format is already on the WIKI, add your game's name to the list at the bottom of the format page, keeping alphabetical order, and then add your game to the list of [[GRAFs]].

If you pass the search test (i.e. the game isn't on the WIKI), you will next need to edit the correct list on the [[GRAFs]] page and add the title of the game to the list. The current list is sorted alphabetically, so please follow that convention!

If your format is for a game demo, as opposed to the full version, please place the following label immediately after the name:
<pre>{{DemoTag}}</pre>
This will result in: {{DemoTag}}<br>
If you pay attention, you'll note that some names have a colored game platform name/abbreviation following them, and before the format link(s). If your format is for a console game (not for the PC), please use the correct tag after the name, as follows:
<pre>
3DO:       {{3DOTag}}
Dreamcast: {{DreamcastTag}}
Gamecube:  {{GamecubeTag}}
PS1:       {{PS1Tag}}
PS2:       {{PS2Tag}}
PSP:       {{PSPTag}}
X-Box:     {{XBoxTag}}</pre>
''To request tags for additional platforms, please leave a comment on the [[Talk:Adding a Format]] page.''<br>
This will result in one of the following labels: {{3DOTag}} {{DreamcastTag}} {{GamecubeTag}} {{PS1Tag}} {{PS2Tag}} {{PSPTag}} {{XBoxTag}}

''NOTE: There is a difference between the PS1 and the PSX!!! The PS1 was the original Playstation system released by Sony, and the PSX was a souped-up version of the PS1 released shortly thereafter, with the intention of being an all-in-one media center. The PSX failed miserably, the PS1 did not. I'm not sure if there are any differences between games on the PS1 and those on the PSX (if they are even seperate), but still, watch when you post a format for the PS1 or the PSX!!!''

Samples:
* Sample Game ( '''[[GFFC|*.xxx]]''' )
* Sample Game {{DemoTag}} ( '''[[GFFC|*.xxx]]''' )
* Sample Game {{PS2Tag}} ( '''[[GFFC|*.xxx]]''' )
* Sample Game {{DemoTag}} {{XBoxTag}} ( '''[[GFFC|*.xxx]]''' )

==== Naming Conventions ====
After adding the name of the game, you'll have to create a link. When choosing the name of the new page, you should use the game's name, with the same capitalization used on the game's box or case.
* If the game is a demo, you will also want to include the text '''(Demo)''' immediately after the game's name.
* If the game is not for the PC, you will next want to include what system it's for.
* Lastly, include (in all caps) the extension for the format.
In the label for the link, include each extension that uses that format in lower-case letters.
Examples:
* <nowiki>[[Sample Game ARCHIVE001|*.archive001]]</nowiki>
* <nowiki>[[Sample Game PS2 ARCHIVE001|*.archive001]]</nowiki>
* <nowiki>[[Sample Game XBOX ARCHIVE001|*.archive001 *.xyz *.zzz]]</nowiki>
* <nowiki>[[Sample Game (Demo) GAMECUBE ARCHIVE001|*.archive001 *.xyz *.zzz]]</nowiki>
Should you be adding multiple formats for the same game on the same system, please start a seperate page for each format. Each seperate link should be included in its own set of parenthesis after the game title/platform tag, as follows:
* Sample Game ( '''[[GFFC|*.archive001]]''' ) ( '''[[GFFC|*.xyz]]''' ) ( '''[[GFFC|*.abc *.zzz]]''' )
* Sample Game {{DemoTag}} {{XBoxTag}} ( '''[[GFFC|*.archive001]]''' ) ( '''[[GFFC|*.xyz]]''' ) ( '''[[GFFC|*.abc *.zzz]]''' )

=== Editing the page ===
When you've submitted the edited page, it will create a red link that you can click on to edit the new page. Click on it, and copy the following text onto it (NOTE: this may not be the most current template to use. Make sure to check the page [[Sample Game 1 PAK]] for the most current template, as that is where changes are first made):
 <nowiki>{{GRAFPageHeader}}</nowiki>
 
 == FILE EXTENSION ==
 <nowiki>{{GRAFPageMisc</nowiki>|
 date_posted=<nowiki>~~~~~</nowiki>}}
 
 === Format Specifications ===
 <nowiki>{{GRAFPageFormat</nowiki>|1='''None written yet.'''}}
 
 === Notes and Comments ===
 '''None'''
 
 === MultiEx BMS Script ===
 '''<nowiki>{{NoBMSScript}}</nowiki>'''
 
 === Supported by Programs ===
 '''<nowiki>{{NoProgramSupport}}</nowiki>'''
 
 === Links ===
 '''None'''
 
 === Games ===
 '''None'''
 
 <nowiki>{{GRAFPageFooter}}</nowiki>

==== Filling out the Template ====

<blockquote>''Note: This was moved verbatim from [[Sample Game 1 PAK]], and still has to be edited to stand alone.''</blockquote>

<pre>
{{GRAFPageHeader}}

== PAK ==
{{GRAFPageMisc|date_posted=20:45, 26 Apr 2006 (EDT)}}

If your format is non-archive, add the parameter format_type= to it. You then choose from one of the following: {{FormatAudio}}, {{FormatMiscellaneous}}, or {{FormatVideo}}. For example, if my format is a picture format (video), I would place on the format page:
{{GRAFPageMisc|format_type={{FormatVideo}}|date_posted=XXX}}.
If your format is not Little Endian (and thus Big Endian), add the text endian_order={{EndianBig}} to it. For example, this would be placed on the format page:
{{GRAFPageMisc|endian_order={{EndianBig}}|date_posted=XXX}}.
You can also use these together. For example, if my above examples were for the same format:
{{GRAFPageMisc|format_type={{FormatVideo}}|endian_order={{EndianBig}}|date_posted=XXX}}
Lastly, note that the exact order of the parameters isn't important. For example,
{{GRAFPageMisc|date_posted=XXX|endian_order={{EndianBig}}|format_type={{FormatVideo}}}}
will display just the same as
{{GRAFPageMisc|format_type={{FormatVideo}}|date_posted=XXX|endian_order={{EndianBig}}}}
or
{{GRAFPageMisc|format_type={{FormatVideo}}|endian_order={{EndianBig}}|date_posted=XXX}}.

=== Format Specifications ===
{{GRAFPageFormat|1=char {15} &nbsp;&nbsp; - Header {{Constant|(Sample Game PAK)}}<br>
byte {1} &nbsp;&nbsp;&nbsp; - null Padding<br>

{{BlockDescription|// For each file}}<br>
:char {16} &nbsp;&nbsp; - File name {{InlineComment|(null padded)}}
:uint32 {4} &nbsp; - File size
:byte {x} &nbsp;&nbsp;&nbsp; - File data}}

Note that when you use the {{GRAFPageFormat}} template, if you use any other templates within it, such as {{InlineComment}} or {{Unknown}}, you need to place a 1= right after the pipe character (|). For instance, {{GRAFPageFormat|{{BlockDescription|This is a block description}}}} will display as '''None written yet'''. However, {{GRAFPageFormat|1={{BlockDescription|This is a block description}}}} will display as '''This is a block description''', in blue text. If no other templates are used, the 1= is completely optional, but it should still be left in.

Block section descriptions should use the {{BlockDescription}} template, like in the example above.

Field tags can be one of the following:
uint16 {2} for 2-byte-long unsigned integers
uint32 {4} for 4-byte-long unsigned integers
char {x} for x-byte-long character data
byte {x} for x-byte-long hexadecimal data
int16 {2} for 2-byte-long signed integers
int32 {4} for 4-byte-long signed integers
float {x} for x-byte-long floats

char {1} or byte {1} should be used for any 1-byte-long fields, and if you need a tag for fields 3 bytes long, or 5 bytes or longer, you can use
char {x} or something like uint48 {6}. If you use
uintx {x} or intx {x}, note that the first number in the tag (the first x) is equal to the field's length * 8, so if a field is 4 bytes long, the first number would be 32. The second number (the second x) should be the field's actual length in bytes. Field tags themselves should be thirteen characters long from the beginning of the tag to the dash, inclusive, with multiple spaces using &nbsp;, as seen in the above example.

Unknown values should use the {{Unknown}} template. If you have an educated guess for what an unknown value might be, you should use
{{Unknown| '' Educated guess '' }}, where Educated guess is, of course, your educated guess.

Literal strings, such as "Hello world" or "Wuzup?" should use the Constant template and should be enclosed within parenthesis following the field description. E.g.
{{Constant|("Hello world")}} Non-printable characters (NPC's), such as nulls, should be written as just the character's ASCII code in hexadecimal, e.g. 00 for a null. Nulls themselves can also be represented by the word "null". Multiple NPC's should be seperated from each other and any literal  strings with spaces. For instance,
{{Constant|("Hello world" 00 21)}} or
{{Constant|("Hello world" null 21)}}

Any short notes should be enclosed in parenthesis and use the InlineComment template after the field description, e.g.
{{InlineComment|(This is a comment)}}. Longer notes should go in the "Notes and Comments" section.

=== Notes and Comments ===
None

You can create new section headings in this section, if necessary. If you do this, you should start with level four headings, e.g.
==== This is a level four heading ====
and working farther in (with level five, etc. headings) if necessary. You can name these section headings whatever way suits you best, so long as they are somewhat descriptive of the notes in that section.

=== MultiEx BMS Script ===
{{NoBMSScript}}

IMPORTANT: DO NOT USE TEMPLATES WITH THE BMS SCRIPT TAG!!!
The current BMS plugin doesn't work with templates, and as a result, it cannot be put on a page partially contained in a template. Therefore, assuming an oversimplified version of the BMS plugin, using something like

{{Script|author=someguy|ext=abc|script=foobar}}

with Template:Script containing

<bms author="{{{author}}}" ext="{{{ext}}}">
{{{script}}}
</bms>

the plugin returns an error, and you see lots of brackets. Templates can still be used outside of the <bms> tag with no consequense, though. Therefore,

{{template1}} <bms tag here> {{template2}}

will work perfectly fine.

=== Supported by Programs ===
{{NoProgramSupport}}

If your format is supported by any programs, you should list each program on its own line, and each line should start with an asterisk (*). This will automatically make a list.
If your format is supported by MultiEx Commander, replace the line {{NoProgramSupport}} with {{ProgramSupportMexcom}}. Note that if MexCom supports a given format, its tag should always be the first program on the list.
If your format is supported by Game Extracter, replace the line {{NoProgramSupport}} with {{ProgramSupportGameExtracter}}.  Note that if Game Extracter supports a given format, its tag should always be either directly below MexCom's tag (it should be second on the list), if MexCom also supports that format, or it should be at the top of the list.
If your format is supported by any other programs, list them in alphabetical order, and if they have pages on the WIKI, link the name to the corresponding page (otherwise, you can link to the program's official website). For example, if my format is supported by a program called FooBar3000, and there is a page on the WIKI for that program, the link would look like [[FooBar3000]] (if the page name was the same as the name of the program).

For example:
* {{ProgramSupportMexcom}}
* {{ProgramSupportGameExtracter}}
* AnotherGenericFileExtracter
* [[FooBar3000]]
* [http://www.someotherprogram.com SomeOtherProgram]

Without MexCom support:
* {{ProgramSupportGameExtracter}}
* [[FooBar3000]]

Without Game Extracter support:
* {{ProgramSupportMexcom}}
* [[FooBar3000]]

Without either:
* [[FooBar3000]]

=== Links ===
None

=== Games ===
* [[Sample Game 1]] [[PAK|*.pak]] [[ZIP|*.zip]]

Each game listed here should link to its own page. If a game is for a non-PC platform, it should have the platform it's for in parenthesis following the game name, e.g. [[Sample Game 1 (PS2)]] or [[Sample Game 1 (Gamecube)]]. Before you do this, be absolutely sure that the game title is spelled correctly, etc. Also, each extension used by the given game for that format should link to its own page, as seen above.

{{GRAFPageFooter}}

[[Category:Complete Complete| ]] [[Category:Platform PC| ]]

Categories are used for... what do you know... categorizing WIKI pages. There are a number of categories used on the WIKI (somewhere around 50, IIRC), but by the time your page is finished, it will only have between 7 to 10 categories listed in most cases, and you will have to manually list even fewer. The categories you should worry about are those concerning how complete the Format Specifications are, those concerning a BMS script, those concerning what platform the game(s) using the format are for, those concerning how widely used a format is, and those concerning whether the format uses compression/encryption.

Keep in mind that all category tags should include the line {{subst:PAGENAME}} after the pipe character (|), e.g.
[[Category:Cat Name Here|{{subst:PAGENAME}}]]. After a page is saved, the WIKI automatically replaces this line with the page's name. In general, category tags should take the form
[[Category:Cat Name Here|{{subst:PAGENAME}}]]

The specification completion categories are fairly straightforward to use. If most of a file's format is unknown (and chances are therefore good that it can't be supported by MexCom yet), one should use the category Complete WIP, indicating that the format is a work in progress. If the format is reasonably complete (few unknown values), you should use the category Complete Almost Done, and if the format is completely known (no unknowns), you should use Complete Complete.

As for BMS scripts, there are only three things you should worry about: if there's no BMS script for a given format, you should have used the template {{NoBMSScript}}, and the appropriate category is added automatically. Similarly, if a BMS script can't be used for a given format, because it's too complex, uses compression/encryption, wrong format type, etc., you should have used the template {{BMSNotApplicable}}, which also automatically adds the appropriate category. If you added a new script for a given format, you should add the category BMS New to the end of the page. Otherwise, don't worry about adjusting this category tag.

Moving on to platforms a given format is used on, in general, category names take the form of Platform *platform name*, e.g. Platform PC or Platform PS2. A full list of appropriate categories follows:
Platform 3DO
Platform PC
Platform XBox
Platform XBox 360
Platform Gamecube
Platform Dreamcast
Platform PS1
Platform PS2
Platform PS3
Platform PSP
More categories will be added as needed.
When adding platform categories, just use all of them that apply. For instance, if a format I was working on was used on the PC and the Gamecube, I would use the categories Platform PC and Platform Gamecube.

Next to last, these categories depend on the number of games known to use a given format. If a format is used by between four and twenty games, you should use the category Format Common. However, if a format is used by more than twenty games, or if it enjoys widespread use outside of the game development community, you should use the category Format Standard. Formats used by fewer than four games shouldn't be worried about.

Finally, the categories for compression and encryption are quite simple. Most of the time, the format you're working on won't use compression or encryption, so you should use the category CE None. If it uses unknown compression/encryption, you'll want to use the category CE Unknown. If you know for sure that a given format uses compression, use the category CE Compressed, and similarly, CE Encrypted for encryption. If a format uses both compression and encryption, skip the individual CE Compressed/CE Encrypted categories and just use CE Both.

After all of this, if you really want to dig deeper into the category system on the WIKI, start your explorations at Category:Categories.
</pre>

See also: [[GRAFTemplate1_Help]]

=== The Last Step ===

Once you've finished your new page, [http://wiki.xentax.com/index.php?title=Template:Latest_Grafs&action=edit edit] the [[Template:Latest Grafs|Latest Grafs]] section on the front page. When doing so, add the link to your new page(s) to the top of the list, and remove an entry or entries from the bottom of the list until it has exactly ten entries again.

[[Category:Tutorials]]