# IUPAG
> **International Union of Pure & Applied Gaming**:
> 
> *"By Gamers, For Gamers: Committed to the Organization, Preservation, & Development of Romhacks"* !!!

:rewind: **History**:  IUPAG was born to address the lack of a standard naming convention for romhacks, specifically, with respect to "naming collisions" (where different hacks have the same name):  This mostly occurs with (1) Translations & (2) Sports games that update rosters to "current year" (i.e. Tecmo, NHL, etc).  However, these "naming collisions" also occur with other hacks: When two different hacks have the same "branding" (name).

:fast_forward: **Philosophy**:  The goal is to provide a "Parent Specification" that is easily customizable according to individual preferences, as well as promote other standards, like good, sane patching practices (like "auto-patching").

For a more in-depth review of our History & Philosophy, feel free to join our Discord:  https://discord.gg/kEe3aUzJ5D

### IUPAG Format
> *IUPAG nomenclature was inspired by "A Guide to IUPAC Nomenclature of Organic Compounds"*.

The format should look like this:
```
Title <sep> Subtitle (@Dev, Pub)-(#Region)-(vDate)-(revX.Y.Z)-(T-Lang) [flag]-{Attributes}-(MetaInfo).ext
```
Where `<sep>` is the "seperator" that is used between the Title & Subtitle:  For Parents, the seperator is a dash (`-`).  For Clones, the seperator is a dash-semicolon (`-;`).  For Translations, the seperator is semicolon-equals (`;=`).  And for Romhacks, the seperator is the tilde (`~`).  The seperator is used even if the Subtitle is null/empty/blank.

Also, notice that the above "Tags" are "named tags" with a prefix attached (`@`,`#`,`v`,`rev`,`T-`) that make them easier to parse.

The default ordering of Tags can be read as:
> *"by @Author, for #Region, on vDate, as Revision, in Text/Language, Flagged, with Attributes, and MetaInfo"*.

The following are the formal rules & guidelines for the **IUPAG** naming convention.

However, if you'd rather just see an example to get the "gist" of it, go [HERE](https://gist.github.com/Europia79/14b6f95ae75758618095aef156462d8b)

And if you wanna take it for a "test drive", here's an SNES DAT file, [HERE](https://gist.github.com/Europia79/a0b0e2719a80690913c746f4dfe0aec8)

> [!NOTE]
> Please note that altho IUPAG was developed specifically for romhacks, the naming specification actually extends to Parents & Clones as well:  Which allows for easy integration of romhacks & translations as well as "auto-patching" functionality and "1g1r" functionality, both with less computational strain at runtime.

### :zero: Valid & Invalid Characters
Only 7 Bit ASCII (Low ASCII) characters are allowed:
`a-z A-Z 0-9 SPACE $ ! # % ' ( ) + , - . ; = @ [ ] ^ _ { } ~`

The following characters are not allowed as valid filename characters on the **Windows** Operating System, and hence, forbidden from use: `/ \ ? : * " < > | \n \t`

The most common substitution are replacing a colon (`:`) with a semi-colon (`;`), and replacing any double-quotes (`"`) with single-quotes (`'`).  Fractions, like one-half (`½`), that contain a division symbol (slash `/`) can be replaced with an exclamation point (`!`) and represented as `1!2`.

### :one: Title - Subtitle
First, construct the Title & Subtitle with an appropriate seperator and file extension.[^1]

For romhacks, the Title is the same as the Parent/Baserom while the Subtitle is the Hack Name, which can also be prefixed with a "qualifier" of difficulty, patchtype, &/or Holiday Theme, etc.

[^1]: **Title - Subtitle**:  
  **Capitalization**: https://wiki.no-intro.org/index.php?title=Naming_Convention#Capitalization  
  **Japanese Romanization**: https://wiki.no-intro.org/index.php?title=Naming_Convention#Japanese_Romanization

### :two: (\@Developer, Publisher) Tag
Next, add the `(@Developer, Publisher)` Tag.

The developer can be omitted if there's only one Publisher across regions.  However, developer is required if each region has their own publisher.  Altho, the names can be shortened (by omitting "Co.", "Ltd.", etc) and abbreviated.  However, any abbreviations should still be unique.

### :three: (\#Region) Tag
Next, add the `(#Region)` Tag:  And since most development studios are assumed to be targeting hardware devices on the planet Earth, the default region (if unknown) is `(#World)`.  Otherwise, attach an appropriate Planet (or Region on Earth).  Please use the fully qualified name, not an abbreviation,  as at this time, there are no offical ISO designations for the other Planets.  However, this is subject to change (if Elon gets us to Mars).

For Romhacks, attach the "dash revision" that was used as the Parent/Baserom: i.e. `(#USA-11)`.  For Hacks that change the "Region" (NTSC/PAL), please retain the original region and note the change in the `(MetaInfo)` Tag (see below).

### :four: (vDate) Tag
Next, attach a `(vDate)` Tag, in the format: `(vYYYY-MM-DD)`, where "Unix Time Zero" is null/unknown: `(v1970-01-01)`.

### :five: (revision) Tag
Next, construct an appropriate revision tag. Where `00` means Proto, `01` thru `09` mean Alpha/Beta/Demo/Sample.  And `10` (or greater) means an official release for retail sales, while `20` (or greater) means an Aftermarket re-release.

For Romhacks & Translations, this "revision" is simply whatever their "Version Sring" is (which can be absolutely anything).  However, if it's a "Date String", then just convert to an ordinal system, where `00` is the 1st prototype, `01` is the first beta, and `10` is the first non-beta "release".  For Translations, a "percent completetion" is acceptable:  `(rev90%)`.

### :six: (T-Lang) Tag
Next, construct a Language Tag, which is a comma seperated list: e.g. `(T-En,Fr,De,Es,It,Nl,Sv)`[^6]

[^6]: **Language** List: Order of Precedence: https://wiki.no-intro.org/index.php?title=Naming_Convention#Language(s)  
  Currently, there is a proposed change that while the most prevalent language in the West (English), is listed first, that, likewise, the most prevalent languages in the East (Korean, Japanese, Chinese) should be listed LAST (for quicker EYEdentification at a glance [sic]).

### :seven: \[Dump Info\] Flag
Next, attach a "dump info flag" (even if empty):

`[d][cr][f][h][m][n][p][t][tr][o][u][v][b][i][x][s][a][!][$]`:

| :checkered_flag: | Status | Description |
| :--------------: | :--- | :---------- |
| `[a]` | Alt | Alternate re-release w/ unknown version (deprecated). |
| `[b]` | Bad | Bad Dump &/or damaged image. |
| `[cr]` | Cracked | Copy Protection removed. |
| `[d]` | Diff | Small "GP" patch file (in any format) |
| `[f]` | Fixed | Hacked with improvement &/or "fix" (deprecated). |
| `[h]` | Hacked | Intentional Hack but not verifed as [$] (good). |
| `[i]` | Incomplete | Not fully translated (deprecated). |
| `[m]` | Modified | Unintentional modification: i.e. Has a save file. |
| `[n]` | re-Named | Filename is different from Parent (translated) (deprecated). |
| `[o]` | Overdump | The image is damaged (too much data). |
| `[p]` | Pirate | Violates international IP (deprecated). |
| `[s]` | Sample | i.e. Alpha,Beta,Proto,Demo,Sample (proposal only). |
| `[t]` | Trained | Adds cheats &/or cheat menu. |
| `[tr]` | Translated | Translated, but not verifed as [$] (good). |
| `[u]` | Underdump | The image is damaged (missing data). |
| `[v]` | Virus | Infected with a virus. |
| `[x]` | Bad | Bad Checksum or Alternative Checksum Routine. |
| `[!]` | Good | Verified Good Dump. |
| `[$]` | Good | Verified Good Hack (or Translation). |
| `[]` | Unknown | Nothing is known about the dump. |

### :eight: {Attribute} Tag
Next, construct an "attributes" tag.

For Parents/Clones, the attributes tag generally lists `{<Number of Players>;<Genre1,Genre2>;<Controller Support>}`.[^8]

[^8]: **{Attributes}** Tag:  Most games (with the exception of Sports) are assumed to be `{1P}` (one-player), and hence, such an "attribute" can be omitted for brevity.  However, `{1P}` is required for single player "Sports" games, since they are the exception to the general rule (that most "Sports" games are multiplayer).  Furthermore, in order to give the best search functionality, a 4-player game (for example) would be formatted as `{2P,4P}`.  Some example queries: "`{2P}`" (one-player/two-player support), "`{2P`" (at least two-player), "`{2P,`" (at least three-player), and "`4P}`" (maximum 4-player).

Romhacks inherit all these attributes, by default, and instead list any extra patches that were applied (if any).  A null list is denoted with a double-dash via `[$]-{--}.ext`:  This is the clean, base hack without any optional or external patches applied to it.

These genres & gametypes are expressed in `L33TC0D3` to be unique, easier to parse, and more easily transformable to other systems:
| `{G3NR3}` | Description
| -------:  | :-----------
| `{B34T}`  | Beat'em up. |
| `{PL4T}`  | "1-dimensional" Platformer with Linear Progression (on a single "axis" left-to-right). |
| `{1A}`    | (1)-dimensional Platformer with Adventure & requiring exploration to progress. |
| `{2A}`    | (2)-dimensional Action Adventure with an Overhead, Birds-eye view. |
| `{3A}`    | (3)-dimmenional Action Adventure with a 3D (Dungeon Crawler) view. |
| `{4A}`    | (A)ction or (H)ybrid Adventure with multiple game-modes. |
| `{5A}`    | (S)trategy Adventure: e.g. (Starflight). |
| `{6A}`    | (S)pace Adventure (with alt-gravity &/or alt-physics). |
| `{7A}`    | (T)ext-based Adventure: e.g. (Erika to Satoru no Yume Bouken). |
| `{8A}`    | (B)eat'em up view / isometric perspective Action Adventure: e.g. (Time Lord). |
| `{9A}`    | (P)ower-Pad (A)dventure game: e.g. (Street Cop - Manhattan Police). |
| `{1RPG}`  | (1)-dimensional Platformer with RPG elements (like xp & level-ups). |
| `{2RPG}`  | (2)-dimensional RPG with an Overhead, Birds-eye view: Traditional JRPGs. |
| `{3RPG}`  | (3)-dimensional RPG with a 3D (Dungeon Crawler) view. |
| `{4RPG}`  | (A)ction (H)ybrid RPG with multiple game-modes, like 1/2 or 2/3 (for example). |
| `{5RPG}`  | (S)trategy RPG (Turn Based Strategy): e.g. (Shining Force). |
| `{5RTS}`  | (S)trategy RTS (Real Time Strategy): e.g. (Command & Conquer). |
| `{1S&P}`  | (1)-dimensional (S)trategy (&) (P)uzzle: e.g. (A Boy & His Blob). |
| `{2S&P}`  | (2)-dimensional (S)trategy (&) (P)uzzle: e.g. (Quinty)/(Mendel Palace). |
| `{3S&P}`  | (3)-dimensional (S)trategy (&) (P)uzzle: e.g. (Portal). |
| `{4S&P}`  | (A)ction (H)ybrid (S)trategy (&) (P)uzzle: e.g. (Spy vs Spy). |
| `{S1M}`   | Simulation: e.g. (SimCity),(The Sims),(Flight Simulators), etc. |
| `{$SIM}`  | Strategy Simulation: e.g. (Koei Historical Warfare games). |
| `{QZ}`    | Quiz Game:  e.g. (King of Kings by Wisdom Tree). |

### :nine: (MetaInfo) Tag
Next, construct the `(MetaInfo)` Tag, which is a semi-colon seperated List used for a variety of information, like:

For Parents/Clones:
- `(Unl; Aftermarket; Steam, Itch, GOG; Windows, Mac, Linux; Alpha).ext`[^9]

[^9]: **(MetaInfo)** Tag:  Please note that eventho this tag is a semi-colon seperated List, that each "element" within the List can also be a CSV (comma seperated) List, itself.  And the "order of precedence" is: Highest priority (listed first): Unl, Pirate, Aftermarket.  While the lowest priority (listed last) are the Dev Status Flags:  Proto, Alpha, Beta, Demo, Sample, Snapshot, and also Reprint & Alt.

For Romhacks:
- The number of Exits in a Super Mario World romhack: `(Exits=100).sfc`
- The number of Stars in a Super Mario 64 romhack: `(Stars=120).z64`
- The Mapper number of an NES Hack with multiple versions: `(M#001).nes`/`(M#004).nes`

For Translations:
- `(Literal Translation).ext`
- `(Localized Translation).ext`

For Patches:
- "Dependency Declarations": aka "Addendum" `(&)` patches.

And including an `nsfw` desingation for nudity (since "strong language", "violence", & "blood & gore" are "par for the course" for most video games while nudity is not).  As well as other "metainfo", like `(Special Edition)`, for example.

### :keycap_ten: The Title Transformation Rules
Apply the "Title Transformation Rules":  The "Series Rule", the "Parity Rule", & the "Uniqueness Rule".[^10]

The best example of the "Series Rule" would be "The Quintet Trilogy" (on SNES).

The best example of the "Parity Rule" would be EA's NHL series (on both SNES & GEN/MD).

The best example of the "Uniqueness Rule" would be the Pokemon series (on GB/GBC/GBA/etc).

[^10]: Examples of the **Title Transformation Rules**:  The "Series Rule", the "Parity Rule", & the "Uniqueness Rule":  
  https://gist.github.com/Europia79/14b6f95ae75758618095aef156462d8b

### 11. Universe Prefixes
For different games that take place in the same fictional "Game Universe", attach an appropriate prefix: e.g. Mario, Pokemon, Simpsons, Sonic, TMNT, Zelda, etc.  The exception here are games based on TV Cartoons (by Disney, Warner, & Hanna-Barbera), which together, all get the `DIS` prefix.  However, for "Eastern Cartoons" (Anime), use the `AM3` prefix.

### 12. Sports Prefixes
Finally, attach one of the below "Sports" prefixes (if applicable):

|              :id: | Prefix    | Description |
| :---------------: | :-------- | :---------------------------------------------------- |
|             :gun: | **[1R]**  |  **(1)-dimensional (R)un-N-gun**:  Platform Shooters. |
|             :gun: | **[2R]**  |  **(2)-dimensional (R)un-N-gun**:  Overhead Shooters. |
|             :gun: | **[3R]**  |  **(3)-dimensional (R)un-N-gun**:  FPS & Gallery Shooters: `{LG}` suffix indicates Light-gun compatible. |
|            :bomb: | **[4S]**  |  **(H)ybrid (S)hooter** with multiple game modes (like `1R/2R`, `1R/5H`, or `2R/3R` (etc), but NOT `5H/5V`). |
|        :airplane: | **[5F]**  |  **(S)hooter (F)lying**:  1st & 3rd Person, 3D SIM &/or Action Arcade style. |
|        :airplane: | **[5H]**  |  **(S)hooter (H)orizonal**. |
|        :airplane: | **[5HV]** |  **(S)hooter (H)orizonal & (V)ertical**:  Multiple game modes: `5H` & `5V`. |
|        :airplane: | **[5V]**  |  **(S)hooter (V)ertical**. |
|        :airplane: | **[5Z]**  |  **(S)hooter Miscellaneous(Z)**: Isometric scrolling &/or Multi-directional without auto-scrolling (etc). |
|          :trophy: | **[6O]**  |  **(O)lympic (G)ames**. |
|     :snowboarder: | **[720]** |  **Skating, Skiing, & Snowboarding** games w/ 180, 360, `[720]`, & 1080 tricks. |
|               :b: | **[841]** |  =`BALL`: **Dodgeball, Kickball, Volleyball**, & other Misc Sports, like Speedball & Rugby, etc. |
|          :guitar: | **[964]** |  **Rhythm & Action** games: (P)ower-Pad, (G)uitar, & Controller Rhythm & (A)ction games. |
|         :warning: | **[BIOS]** | Console **BIOS** file: "(B)asic (I)nput (O)output (S)ystem".
|          :wrench: | **[PRG]** | **Program** or System Utility to test & diagnosis problems.
|        :game_die: | **BG**    |  **(B)oard (G)ames** & TV show games: e.g. (Monopoly)/(Wheel of Fortune). |
|            :boat: | **BMC**   |  **Fishing** games: (B)ass (M)aster (C)lassic. |
|  :checkered_flag: | **F1**    |  **(F)ormula-(1)**: 1st-person & 3rd-person Racing games with a 3D view. |
|        :fuelpump: | **F2**    |  **(F)ormula-(2)**: 2nd-person Racing games with a birds-eye, overhead view. |
|       :high_heel: | **F7**    |  **(F)amily (T)rainer**: All other Power-Pad games (except sports: `6O` & `964`). |
|          :soccer: | **FIFA**  |  **Soccer** games:  (F)ederation (I)nternationale de (F)ootball (A)ssociation. |
| :european_castle: | **K0EI**  |  **Koei** (& Koei-like knockoff) strategy games:  Aerobiz, Gemfire, Genghis, Nobunaga, Romance, Sangokushi, etc. |
|        :baseball: | **MLB**   |  **Baseball** games:  (M)ajor (L)eague (B)aseball. |
|      :basketball: | **NBA**   |  **Basketball** games:  (N)ational (B)asketball (A)ssociation. |
|        :football: | **NFL**   |  **Football** games:  (N)ational (F)ootball (L)eague. |
|      :maple_leaf: | **NHL**   |  **Hockey** games:  (N)ational (H)ockey (L)eague. |
|         :pushpin: | **P1N**   |  **Pinball** games: IFPA: (I)nternational (F)lipper (P)inball (A)ssocation. |
|           :8ball: | **P88I**  |  **Table-top (P)ool, (8)-ball, & (B)(I)=Billiards** games. |
|         :bowling: | **PB4**   |  **Bowling** games:  (P)rofessional (B)owlers (A)ssociation: PBA. |
|            :golf: | **PG4**   |  **Golf** & mini-golf games:  (P)rofessional (G)olfers (A)ssociation: PGA. |
|          :unlock: | **PZ**    |  **(P)uzzle** games:  Like Tetris, Puyo Puyo, Panel de Pon, etc. |
|          :tennis: | **T3N**   |  **Tennis** games: Association of Tennis Professionals: ATP. |
|              :vs: | **VS**    |  **(V)ERSU(S)**, Two-Player Fighting games & Boxing games (`VS BX`), but NOT "Beat'em-Ups". |
|           :clubs: | **WSOP**  |  **Gambling** games:  (W)orld (S)eries (O)f (P)oker. |
|          :muscle: | **WWF**   |  **Wrestling** games:  (W)orld (W)restling (F)ederation (aka WWE). |