Difference between revisions of "User:Ivan/Mod format WIP"

From VCMI Project Wiki
Jump to: navigation, search
m
 
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
Sandbox, testing syntax highlight
+
Future mod format, WIP
  
 +
Based on [[modding guidelines]] page, any parts implemented in code should be moved to original page from here
 +
=Filesystem format=
 +
 +
All files from one mod are placed into mod directory located in Mods/ directory. Name of directory also serves as unique identifier of mod
 +
 +
== Main mod directory ==
 +
Main mod directory contains following elements:
 +
* main mod configuration file
 +
* resources directory
 +
* overrides directory
 +
* content directory (deprecated)
 +
 +
=== Main mod configuration file ===
 +
File named "mod.json", contains all data necessary to load this mod into modding system.
 +
 +
See [[#Mod configuration format|mod configuration format]] for description
 +
=== Resources directory ===
 +
Contains all files that were added by mod, organized according to [[#Data directories|game data directories]]. Files placed here are local to mod and won't replace any file from another mod.
 +
<pre>
 +
Resources/config/object.json
 +
...
 +
Resources/Sprites/image.png
 +
</pre>
 +
=== Overrides directory ===
 +
Directory used to override files from Heroes III or from other mods. To override file modder must create directory with name of mod (or "core" for Heroes III files) and place all overrides in it, using same name and path as targeted mod.
 +
<pre>
 +
Overrides/someMod/config/object.json
 +
...
 +
Overrides/someMod/image.png
 +
</pre>
 +
=== Content directory ===
 +
Acts as game root directory and contains most of files from this mod
 +
To avoid conflicts it is adviced to use subfolders with the name of mod:
 +
<pre>
 +
Content/Data/myMod/
 +
...
 +
Content/Sprites/myMod/
 +
</pre>
 +
 +
See [[#Data directories|game data directories]] for description on where which files should be placed.
 +
 +
== Data directories ==
 +
Can be any of the following:
 +
* '''data/''' - unorganized files, mostly bitmap images (.bmp, .png, .pcx) and some rarely changed files like fonts
 +
* '''config/''' - json configuration files
 +
* '''maps/''' - h3m maps added or modified by mod
 +
* '''music/''' - music files. Ogg and Mp3 are supported with ogg being recommended for mods.
 +
* '''sounds/''' - sound files, in wav format.
 +
* '''sprites/''' - animation as well as any image sets (H3 .def files or VCMI .json files)
 +
* '''video/''' - video files, .bik or .smk. In future there may be support for other formats
 +
 +
=Mod configuration format=
 
<syntaxhighlight lang="javascript">  
 
<syntaxhighlight lang="javascript">  
 
{
 
{
−
"artifacts":
+
    // Name of your mod. While it does not have hard length limit
−
[
+
    // it should not be longer than ~30 symbols to fit into allowed space
−
{
+
    "name" : "My test mod",
−
"id": 146, /* axe of smashing */
+
   
−
"bonusesPerLevel":
+
    // Version of the mod. Consists from up to 3 numbers:
−
[
+
    // 1) Major - changed when there is large change in functionality
−
{
+
    // 2) Minor - some minor changes notable by players
−
"level": 6,
+
    // 3) Patch - small bugfix releases
−
"bonus": ["PRIMARY_SKILL", 1, 0, 0]
+
    // Minor and Patch numbers are assumed to be 0 if not specified
−
}
+
    // Used during updating and in dependencies resolution
−
]
+
    "version" : "1.0.2"
−
},
+
   
−
{
+
    // author of mod. Can be nickname, real name or name of team
−
"id": 147, //mithril mail
+
    "author" : "Anonymous"
−
"bonusesPerLevel":
+
   
−
[
+
    // Home page of mod or link to forum thread
−
{
+
    "weblink" : "http://example.com"
−
"level": 1,
+
 
−
"bonus": ["STACK_HEALTH", 1, 0, 0]
+
    // Type of mod, e.g. "Town", "Artifacts", "Graphical". Should be predefined list
−
}
+
    "modType" : "Graphical"
−
]
+
−
},
+
    // More lengthy description of mod. No hard limit
−
{
+
    // TODO: show it in some kind of mod manager
−
"id": 148, //sword of sharpness
+
    "description" : "My test mods that add a lot of useless stuff into the game",
−
"bonusesPerLevel":
+
 
−
[
+
    // Download URL, used only in repository
−
{
+
    "download" : "http://example.com/packages/1.1.zip",
−
"level": 1,
+
 
−
"bonus": ["CREATURE_DAMAGE", 1, 0, 0]
+
    // Size of archive for download, in Kb, only repository
−
}
+
    "size" : 9001,
−
]
+
 
−
}
+
    // List of mods that are required to run this one
−
]
+
    "depends" :
 +
    [
 +
        // Can be a single name
 +
        "baseMod",
 +
 
 +
        // Or using range of allowed versions
 +
        "1.0<modName<=5",
 +
    ],
 +
 
 +
    // List of mods that can't be enabled in the same time as this one
 +
    // Similar to dependencies can be either name of mod or mod name + versions range
 +
    "conflicts" :
 +
    [
 +
        "badMod"
 +
    ],
 +
 
 +
    // Following section describes configuration files with content added by mod
 +
    // It can be split into several files in any way you want but recommended organization is
 +
    // to keep one file per object (creature/hero/etc) and, if applicable, add separate file
 +
    // with translatable strings for each type of content
 +
    // See "additional links" at the bottom of page for descriptions of each of these formats
 +
 +
    // list of factions/towns configuration files
 +
    "factions" :
 +
    [
 +
        "config/myMod/faction.json"
 +
    ]
 +
 +
    // List of hero classes configuration files
 +
    "heroClasses" :
 +
    [
 +
        "config/myMod/heroClasses.json"
 +
    ],
 +
 
 +
 
 +
    // List of heroes configuration files
 +
    "heroes" :
 +
    [
 +
        "config/myMod/heroes.json"
 +
    ],
 +
 +
    // list of creature configuration files
 +
    "creatures" :
 +
    [
 +
        "config/myMod/creatures.json"
 +
    ],
 +
 +
    // List of artifacts configuration files
 +
    "artifacts" :
 +
    [
 +
        "config/myMod/artifacts.json"
 +
    ],
 +
 
 +
    // This is description on how files are organized in your mod
 +
    // Optional, by default it follow filesystem format description
 +
    // Example below shows default value
 +
    "filesystem":
 +
    {
 +
        "":
 +
            [
 +
                {"type" : "dir", "path" : "/Content"}
 +
            ]
 +
    }
 
}
 
}
−
</syntaxhighlight>  
+
</syntaxhighlight>
  
−
<syntaxhighlight lang="cpp">  
+
=Repository index format=
−
int CHeroClass::chooseSecSkill(const std::set<int> & possibles) const //picks secondary skill out from given possibilities
+
This is file that contains index of all mods in repository
 +
<syntaxhighlight lang="javascript">  
 
{
 
{
−
if(possibles.size()==1) /* picks secondary skill out from given  */
+
    // timestamp when this index was updated last time, uses unix time
−
return *possibles.begin();
+
    "timestamp" : 1234567890,
−
int totalProb = 0;
+
 
−
for(std::set<int>::const_iterator i=possibles.begin(); i!=possibles.end(); i++)
+
    // Main entry, contains actual index
−
{
+
    // Keeping it separate allows to add any necessary metadata in file
−
totalProb += proSec[*i];
+
    "repository" :
−
}
+
    {
−
int ran = rand()%totalProb;
+
        "modname1" : { <mod configuration format> },
−
for(std::set<int>::const_iterator i=possibles.begin(); i!=possibles.end(); i++)
+
        "modname2" : { <mod configuration format> },
−
{
+
            ...
−
ran -= proSec[*i];
+
    }
−
if(ran<0)
 
−
return *i;
 
−
}
 
−
throw std::runtime_error("Cannot pick secondary skill!");
 
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 12:22, 25 July 2013

Future mod format, WIP

Based on modding guidelines page, any parts implemented in code should be moved to original page from here

Filesystem format

All files from one mod are placed into mod directory located in Mods/ directory. Name of directory also serves as unique identifier of mod

Main mod directory

Main mod directory contains following elements:

  • main mod configuration file
  • resources directory
  • overrides directory
  • content directory (deprecated)

Main mod configuration file

File named "mod.json", contains all data necessary to load this mod into modding system.

See mod configuration format for description

Resources directory

Contains all files that were added by mod, organized according to game data directories. Files placed here are local to mod and won't replace any file from another mod. 

Resources/config/object.json
...
Resources/Sprites/image.png

Overrides directory

Directory used to override files from Heroes III or from other mods. To override file modder must create directory with name of mod (or "core" for Heroes III files) and place all overrides in it, using same name and path as targeted mod. 

Overrides/someMod/config/object.json
...
Overrides/someMod/image.png

Content directory

Acts as game root directory and contains most of files from this mod To avoid conflicts it is adviced to use subfolders with the name of mod: 

Content/Data/myMod/
...
Content/Sprites/myMod/

See game data directories for description on where which files should be placed.

Data directories

Can be any of the following:

  • data/ - unorganized files, mostly bitmap images (.bmp, .png, .pcx) and some rarely changed files like fonts
  • config/ - json configuration files
  • maps/ - h3m maps added or modified by mod
  • music/ - music files. Ogg and Mp3 are supported with ogg being recommended for mods.
  • sounds/ - sound files, in wav format.
  • sprites/ - animation as well as any image sets (H3 .def files or VCMI .json files)
  • video/ - video files, .bik or .smk. In future there may be support for other formats

Mod configuration format

 
{
    // Name of your mod. While it does not have hard length limit
    // it should not be longer than ~30 symbols to fit into allowed space
    "name" : "My test mod",
    
    // Version of the mod. Consists from up to 3 numbers:
    // 1) Major - changed when there is large change in functionality
    // 2) Minor - some minor changes notable by players
    // 3) Patch - small bugfix releases
    // Minor and Patch numbers are assumed to be 0 if not specified
    // Used during updating and in dependencies resolution
    "version" : "1.0.2"
    
    // author of mod. Can be nickname, real name or name of team
    "author" : "Anonymous"
    
    // Home page of mod or link to forum thread
    "weblink" : "http://example.com"

    // Type of mod, e.g. "Town", "Artifacts", "Graphical". Should be predefined list
    "modType" : "Graphical"
 
    // More lengthy description of mod. No hard limit
    // TODO: show it in some kind of mod manager
    "description" : "My test mods that add a lot of useless stuff into the game",

    // Download URL, used only in repository
    "download" : "http://example.com/packages/1.1.zip",

    // Size of archive for download, in Kb, only repository
    "size" : 9001,

    // List of mods that are required to run this one
    "depends" :
    [
        // Can be a single name
        "baseMod",

        // Or using range of allowed versions
        "1.0<modName<=5",
    ],

    // List of mods that can't be enabled in the same time as this one
    // Similar to dependencies can be either name of mod or mod name + versions range
    "conflicts" :
    [
        "badMod"
    ],

    // Following section describes configuration files with content added by mod
    // It can be split into several files in any way you want but recommended organization is
    // to keep one file per object (creature/hero/etc) and, if applicable, add separate file
    // with translatable strings for each type of content
    // See "additional links" at the bottom of page for descriptions of each of these formats
 
    // list of factions/towns configuration files
    "factions" :
    [
        "config/myMod/faction.json"
    ]
 
    // List of hero classes configuration files
    "heroClasses" :
    [
        "config/myMod/heroClasses.json"
    ],


    // List of heroes configuration files
    "heroes" :
    [
        "config/myMod/heroes.json"
    ],
 
    // list of creature configuration files
    "creatures" :
    [
        "config/myMod/creatures.json"
    ],
 
    // List of artifacts configuration files
    "artifacts" :
    [
        "config/myMod/artifacts.json"
    ],

    // This is description on how files are organized in your mod
    // Optional, by default it follow filesystem format description
    // Example below shows default value
    "filesystem":
    {
        "":
            [
                {"type" : "dir",  "path" : "/Content"}
            ]
    }
}

Repository index format

This is file that contains index of all mods in repository 

 
{
    // timestamp when this index was updated last time, uses unix time
    "timestamp" : 1234567890,

    // Main entry, contains actual index
    // Keeping it separate allows to add any necessary metadata in file
    "repository" :
    {
        "modname1" : { <mod configuration format> },
        "modname2" : { <mod configuration format> },
            ...
    }
}
Retrieved from "https://wiki.vcmi.eu/index.php?title=User:Ivan/Mod_format_WIP&oldid=1231"