Help:Adding a format

From XentaxWiki
Revision as of 22:21, 11 December 2010 by Dinoguy1000 (talk | contribs) (bypass redirect)

Jump to: navigation, search

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

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

FAQ

What about multiple versions of the same game?
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.

First and foremost, make sure the format you want to add isn't already on the WIKI. You can do this by 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!

Naming Conventions

Firstly, find where your game would be on the GRAFs page. insert a new line with an asterisk (*) at the beginning of the line, followed by the game's name. Make sure to watch capitalization!
For example:

* Sample Game 1

If your format is for a game demo, as opposed to the full version, please place the following label immediately after the name:

{{DemoTag}}

This will result in: Template:DemoTag
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:

3DO:       {{3DOTag}}
Dreamcast: {{DreamcastTag}}
Gamecube:  {{GamecubeTag}}
PC:        {{PCTag}}
PS1:       {{PS1Tag}}
PS2:       {{PS2Tag}}
PSP:       {{PSPTag}}
X-Box:     {{XBoxTag}}

To request tags for additional platforms, please leave a comment on the talk page.
This will result in one of the following labels: Template:3DOTag Template:DreamcastTag Template:GamecubeTag Template:PCTag Template:PS1Tag Template:PS2Tag Template:PSPTag Template: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:

Linking 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. If the format uses more than one extension, choose the one that's used most often for the link. All the extensions should be listed in the link text, as well as in the Games section on the GRAF page. If two or more extensions are used about the same, just choose one of them.

In the label for the link, include each extension that uses that format in lower-case letters. Examples:

  • [[Sample Game ARCHIVE001|*.archive001]]
  • [[Sample Game PS2 ARCHIVE001|*.archive001]]
  • [[Sample Game XBOX ARCHIVE001|*.archive001 *.xyz *.zzz]]
  • [[Sample Game (Demo) GAMECUBE ARCHIVE001|*.archive001 *.xyz *.zzz]]

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:

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):

{{GRAFPageHeader}}

== FILE EXTENSION ==
{{GRAFPageMisc|
date_posted=~~~~~}}

=== Format Specifications ===
{{GRAFPageFormat|1=None written yet.}}

=== Notes and Comments ===
None

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

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

=== Links ===
None

=== Games ===
None

{{GRAFPageFooter}}

Filling out the Template

Note: This was moved from Sample Game 1 PAK, and has undergone some copyediting, though there is still much to do.

Header and Misc Information

{{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}}

A quick note on the date_posted field: the first time you save a page to the WIKI, the value should be ~~~~~ (5 tildes). When the page gets saved, this is automatically replaced with the date and time that the page was saved. On future edits of the page, leave this field alone; it is meant to show when the page was originally created (and thereby when the format was added), not when the last update occurred.

Format Description

=== 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 {{FieldMath|[*2]}}
:byte {x} &nbsp;&nbsp;&nbsp; - File data}}
Template Nesting

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. If no other templates are used, the 1= is completely optional, but it should still be left in.

Sub-blocks

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

Data Types (Field Tags)

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

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.

Strings, Literals and Constants

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)}}

Inline Comments

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.

Inline Math

Any math notes pertaining to the value of a field (e.g. (FieldVal + 32) / 4 = FileSize) should use the {{FieldMath}} template and be enclosed in square brackets, e.g. (if given field should be multiplied by 2):
{{FieldMath|[*2]}}
To use my previous example:
{{FieldMath|[(Val+32)/4]}}
Some magic words for you:

  • Val = field's value
  • + = add
  • - = subtract
  • * = multiply
  • / = divide
  • parenthesis force operation
  • sqrt() = sqare root

Basically, it's just high school algebra all over again. New magic words/symbols will be christened as needed.

Notes and Comments

=== Notes and Comments ===
None
Subheadings

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.

BMS Script

=== 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 consequence, though. Therefore,

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

will work perfectly fine.

Program Support

=== 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]]

External Links and Documentation

=== Links ===
None

Games

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

Footer and Categories

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

See also: GRAFTemplate1_Help

The Last Step

Once you've finished your new page, edit the 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.