Difference between revisions of "Mod Handler"

From VCMI Project Wiki
Jump to: navigation, search
(→‎Objects identifiers)
m
 
(8 intermediate revisions by one other user not shown)
Line 1: Line 1:
−
Mod handler is a class of modding engine which performs the following tasks:
 
−
*Reads all [[packages]] and [[conversions]]
 
−
*Manages mods, turning them on and off. List of active mods is stored in a file.
 
−
*Performs consistency checks: if all mod prerequisistes are met, and if mod files are still present.
 
−
*Synchronizes mod files in online game
 
−
 
 
=Objects identifiers=
 
=Objects identifiers=
−
Every game object ([[creature]], [[artifact]], [[hero]], [[spell]]) needs to have unique identifier (ID). These IDs are assigned dynamically at game start. Original Shadow of Death objects are considered fixed.
+
Every game object ([[creature]], [[artifact]], [[hero]], [[spell]]) needs to have unique numeric identifier (ID). These IDs are assigned dynamically at game start. Original Shadow of Death objects are considered fixed.
 
This solution makes the script independent of mods currently installed and active.
 
This solution makes the script independent of mods currently installed and active.
 +
 +
Additionally, each object has unique string identifier that allows user to quickly call it. This, however, may cause troubles when two different mods try to use same identifier.
 +
String IDS are suggested to be upper-case.
 +
 +
==Wrappers==
 +
 +
Wrappers are object pointers that allow direct access to certain object and simple modification based on it's build-in functions. Only safe functions related to scripted mechanics should be accessible with them.
 +
 +
==usage of identifiers==
  
 
Reference to certain object via script has a form:
 
Reference to certain object via script has a form:
Line 16: Line 19:
 
For example, for package Wake of Gods
 
For example, for package Wake of Gods
 
<pre>WOG.creatures(1)</pre>
 
<pre>WOG.creatures(1)</pre>
−
is Supreme Archangel and
+
is Supreme Archangel ID and
 
<pre>WOG.artifacts(3)</pre>
 
<pre>WOG.artifacts(3)</pre>
−
is Monster's Power.
+
is Monster's Power ID.
 +
 
 +
==Converting identifiers==
 +
 
 +
These calls are equal and interchangeable.
 +
* monID - global numeric indentifier (integer) provided by ModHandler
 +
* index_of_phoenix - local numeric identifier given during package creation
 +
* TWO_HEADED_PHOENIX - string identifier
 +
* monster - object wrapper
 +
 
 +
===Global reference===
 +
<pre>monID = creatures("TWO_HEADED_PHOENIX")
 +
giveCreatureBonus(monID, Bonus)</pre>
 +
OR (overloading)
 +
<pre>giveCreatureBonus("TWO_HEADED_PHOENIX",Bonus)</pre>
 +
===Package reference===
 +
<pre>monID = OurMod.creatures(index_of_phoenix);</pre>
 +
OR
 +
<pre>monID = OurMod.creatures("TWO_HEADED_PHOENIX")</pre>
 +
 
 +
===Object-oriented fashion===
 +
<pre>monster = OurMod.getCreature(index_of_phoenix);
 +
monster.AddNewBonus(Bonus)</pre>
 +
OR
 +
<pre>monster = OurMod.getCreature("TWO_HEADED_PHOENIX")</pre>
 +
 
 +
Discussion: How to differ between numeric IDs, string IDs and wrappers in convenient way? Which of them should be default for user? Which one is recommended?
 +
 
 
==Adventure object identifiers==
 
==Adventure object identifiers==
  
Line 25: Line 55:
  
 
There is a script function which allows to add object as a next subID to the existing group with specific ID.
 
There is a script function which allows to add object as a next subID to the existing group with specific ID.
 +
 +
{{Modding}}

Latest revision as of 18:16, 30 January 2013

Objects identifiers

Every game object (creature, artifact, hero, spell) needs to have unique numeric identifier (ID). These IDs are assigned dynamically at game start. Original Shadow of Death objects are considered fixed. This solution makes the script independent of mods currently installed and active.

Additionally, each object has unique string identifier that allows user to quickly call it. This, however, may cause troubles when two different mods try to use same identifier. String IDS are suggested to be upper-case.

Wrappers

Wrappers are object pointers that allow direct access to certain object and simple modification based on it's build-in functions. Only safe functions related to scripted mechanics should be accessible with them.

usage of identifiers

Reference to certain object via script has a form: 

[PACKAGE_NAME].[OBJECT_TYPE](localID)

For example, for package Wake of Gods 

WOG.creatures(1)

is Supreme Archangel ID and 

WOG.artifacts(3)

is Monster's Power ID.

Converting identifiers

These calls are equal and interchangeable.

  • monID - global numeric indentifier (integer) provided by ModHandler
  • index_of_phoenix - local numeric identifier given during package creation
  • TWO_HEADED_PHOENIX - string identifier
  • monster - object wrapper

Global reference

monID = creatures("TWO_HEADED_PHOENIX")
giveCreatureBonus(monID, Bonus)

OR (overloading) 

giveCreatureBonus("TWO_HEADED_PHOENIX",Bonus)

Package reference

monID = OurMod.creatures(index_of_phoenix);

OR 

monID = OurMod.creatures("TWO_HEADED_PHOENIX")

Object-oriented fashion

monster = OurMod.getCreature(index_of_phoenix);
monster.AddNewBonus(Bonus)

OR 

monster = OurMod.getCreature("TWO_HEADED_PHOENIX")

Discussion: How to differ between numeric IDs, string IDs and wrappers in convenient way? Which of them should be default for user? Which one is recommended?

Adventure object identifiers

As adventure objects have double identifiers (ID and subID), they have to be threated differently. By default, Mod Handler assigns unique ID to each new adventure object class added and their subID is 0.

There is a script function which allows to add object as a next subID to the existing group with specific ID.


Modding related articles

Main articles
Modding changelog Modding guidelines How to create a town mod Mod Handler


Formats
Mod file Format
Town Format Creature Format Hero Classes Format
Artifact Format Animation Format Hero Format
Bonus Format Object Format Spell Format


Work-in-progress formats
Building bonuses Map format
Bonus Type Format Random map template


Outdated pages
Mod system proposal
Retrieved from "https://wiki.vcmi.eu/index.php?title=Mod_Handler&oldid=971"