Create a mod

In this section you will find quick and easy ways to create your own mods. You only need an xml editor (notepad for instance) and a compression program.

Creating a new mod

We need to make a folder with the id of our mod (for instance "beyondar.mod.test"). This folder will store all created elements, such as items, weapons, creatures or missions. Images can be grouped together in subfolders, but XML files must be placed in the root folder of the mod and inside the tag <beyondar>. The following image shows an example of how a mod package is structured.

To test and install your own mod in your device, follow this link.

Entities

To store the data of our entities, create an XML file in the mod root folder, such as "creatures.xml". The following code shows how to create an entity named Beryl.

 <?xml version="1.0" encoding="utf-8"?>
<beyondar version="1.0">
    <entities>
		<entity>
		    <!-- Name to be shown to the user -->
		    <name>Berly</name>
		    <!-- Unique identifier of the entity -->
		    <id>berly_creature_1</id>
		    <!-- Icon that represents the entity -->
		    <icon>creatures/creature_beryl.png</icon>
		    <!-- Icon that represents the entity when it is destroyed-->
			<splashIcon>other/splash.png</splashIcon>
		    <!-- Points to be added to the user if applicable -->
			<points>45</points>
			<!-- How many entities per square meter will be generated-->
			<density>70</density>
			<!-- Description of the resistance points of the entity -->
			<health>
			    <!-- The average hit points -->
				<average>50</average>
				<!-- How much it can be different from the average -->
				<variation>5</variation>
			</health>
			
			<!-- Shield of the entity -->
			<shield>20</shield>
			<!-- Area which the creature will interact witht the user -->
			<area>60</area>
			<!-- Description of the movement -->
			<movement>
			   <!-- How many meters per second the entity will move -->
				<speed>2</speed>
				<!-- where the entity will move. it can be "user", "static" or "away" -->
				<direction>user</direction>
			</movement>
			
			<!-- Description of the entity attack -->
			<attack>
			    <!-- Average health points to subtract per second -->
				<average>7</average>
				<!-- How much it can be diferent from the average -->
				<variation>4</variation>
				<!-- The minum distance (in meters) needed to perform an attack -->
				<area>5</area>
			</attack>
			<!-- When the entity is destroyed, which objects will drop (if applicable) -->
			<drop>
			    <!-- Provavility to drop an object. From 0 to 1-->
				<probability>1</probability>
				<!-- Items that can be dropped (only one will be dropped) -->
				<items>
				    <!-- Description of the item that will be dropped -->
					<item>
						<!-- The id of the item -->
						<id>plasma_rifle_weapon</id>
						<!-- The amount of objects dropped. Not applicable for objects that cannot be stored -->
						<amount>10</amount>
						<!-- The weight of the dropped item (the more weight, the more likely to be dropped) -->
						<weight>1</weight>
					</item>
					 <item>
						<id>ammo_plasma_rifle_object_1</id>
						<amount>1</amount>
						<weight>2</weight>
					</item>
				</items>
			</drop>
		</entity>
	</entities>
</beyondar>
Element Description
entities Entity list.
entity Entity description.
name Name of the entity shown to the user.
id Entity’s unique identifier (all ASCII characters are allowed except for spaces).
icon Image that represents the entity. The path depends on the mod’s folder.
splashIcon Icon shown when the entity is destroyed.
points Points given to the user when the entity is destroyed (if applicable).
density Number of entities per square km.
health Description of the entity’s health points. The hit points of the entities are randomly generated using the average and the variation given.
- average Average of the entities hit points.
- variation Variation of the entities hit points.
shield Shield points definition. When a entity is hit, the hit points are spread evenly between the shield and the hit points.
area Entity interaction area (in meters). At this distance the entity will interact with the user.
movement Definition of the way that the entity moves.
speed Entity speed (in meters/second).
direction When the entities have to move, which direction they will take. There are 3 possibilities:
user: the entity will move towards the user.
away: the entity will move away from the user.
static: the entity will not move ( the same as speed=0 or area =0).
attack Description of how the entity will attack.
- average Average damage dealt by the entity.
- variation Variation of the damage dealt by the entity.
- area Attack range for the entity.
drop Description of which items will be dropped when the entity is destroyed.
- probability Object drop probability when the entity is destroyed. The range is from 0 to 1 (included). For instance: 0.4
- items List of items that the entity can drop.
- item Item description.
-- id Object’s unique identifier to refer to the item (see items and weapons secion).
-- amount The amount of objects that will be dropped. Not applicable for objects that cannot be stored
-- weight Weight in relation to the other items. This weight is used to decide which item drops. For instance, if an item has a weight of 3, it has 3 times more possibilities to drop than an item with a weight of 1.

This is a small example of how to create some entities.

Items/objects

To store data about objects, create an XML file in the mod root folder, such as "objects.xml".

The following code shows how to create an object:

<?xml version="1.0" encoding="utf-8"?>
<beyondar version="1.0">
	<objects>
		<object>
			<!-- Name of the object  -->
			<name>Energy</name>
			<!-- Unique id of this object -->
			<id>energy_object_1</id>
			<!-- Maximum amount in the stack -->
			<maxAmount>20</maxAmount>
			<!-- Default amount for this object. This amount is used when the user starts with this object -->
			<amount>1</amount>
			<!-- Path of the image that represents the item -->
			<icon>objects/object_energy.png</icon>
			<!-- Specify if this object can be used when the user is in the recovery mode -->
			<availableOnRecovery>no</availableOnRecovery>
			<!-- Specify if this object can be stored. If the object can not be stored it will be used when it is absorbed -->
			<canBeStored>yes</canBeStored>
			<!-- When this item can be absorbed (onTouch, onApproaching) -->
			<pickUp>onTotuch</pickUp>
			<!-- List of actions that this object can do when it is used -->
			<actions>
				<!-- Action description. Options available: weapon, providehealth, provideshield, recoveryhelper, provideLife, provideammo, flag -->
				<action>
					<!-- Name of the action -->
					<name>provideHealth</name>
					<!-- Amount provided by this action -->
					<amount>25</amount>
				</action>
			</actions>
		</object>
	</objects>
</beyondar>
Element Description
objects Object list.
object Object description
name Name of the object
id Object’s unique identifier.
maxAmount Maximum amount in the stack. Set to -1 for unlimited.
amount Default number of units. This amount is used when the user starts the game with this object.
icon Path of the image that represents the item. The path is the mod folder.
availableOnRecovery States whether the object can be used during recovery. Possible values:
- yes
- no
canBeStored States whether this object can be used when the user dies. If the object can not be stored it will be used when it will absorbed. Possible values:
- yes
- no
pickUp There are two ways to pick an object up, getting close or contact (if the object is close enough).
- onApproaching: the object will be picked up automatically when the user gets close enough
- onTouch: the object will be picked up when the user touches it.
actions Action list.
- action Definition of which action will be performed when the object is used. These are the allowed actions: weapon, provideHealth, provideShield, recoveryHelper, provideLife, provideAmmo, providePoints, flag (see "actions" section).
-- amount Number of units that the action offers. This element has different uses depending on the action (see "actions" section).
-- weaponId Weapon id of the weapon that will get the specified amount if applicable (see "actions" section).

This link shows a weapon example

Actions

Version 1.0 of the mods has the following actions as available for the objects: provideHealth, provideShield, recoveryHelper, provideLife, provideAmmo, flag.

  • provideHealth: Add health to the player that is using the object (it can also can subtract health if the value is negative).
  • provideShield: Add Shield points (it also can subtract points if the value is negative).
  • recoveryHelper: With this action, the player will be able to reduce the recovery time.
    • The field "amount" specifies the length of the reduction in seconds.
  • provideLife: Add lives to the player that is using it. Use the element "amount" to specify how many lives will be added.
  • flag: This object is used in the missions were the user has to take a map objective. When the user is close to the objective, he or she will have to use an object with this action to complete the mission (for instance, a key).
  • providePoints: Give some points to the user.
  • provideAmmo: This action allows an object to add ammo to a stored weapon.
    • Use the element "weaponId" to specify which weapon will get the ammo, the field "amount" specifies the amount.
<actions>
	<action>
		<name>provideHealth</name>
		<amount>50</amount>
	</action>
	<action>
		<name>provideShield</name>
		<amount>60</amount>
	</action>
	<action>
		<name>recoveryHelper</name>
		<amount>4</amount>
	</action>
	<action>
		<name>provideAmmo</name>
		<amount>10</amount>
		<weaponId>wrap_pistol_weapon</weaponId>
	</action>
</actions>

Weapons

Creating weapons is similar to creating objects. The following code shows how to create a weapon:

<?xml version="1.0" encoding="utf-8"?>
<beyondar version="1.0">
	<weapons>
		<weapon>
			<!-- Name displayed to the user of the weapon -->
			<name>Molecular sword</name>
			<!-- Unique identifyer of the weapon -->
			<id>molecular_sword_weapon</id>
			<!-- Max ammo that can the weapon can have. Use -1 to set that the weapon doen't use amo. for instance a knife -->
			<maxAmount>-1</maxAmount>
			<!-- If maxAmount is not -1, this is the amount of bullets which the user will start -->
			<amount>0</amount>
			<!-- Path of the image that represents the object -->
			<icon>objects/weapon_1.png</icon>
			<!-- Description of the attack of the object -->
<!-- Path of the image that represents the bullet of the weapon --> <iconBullet>bullets/bullet_w1.png</iconBullet> <attack> <!-- Average damage done by this weapon --> <average>5</average> <!-- Damage variation --> <variation>3</variation> <!-- In which distance this weapon can be used --> <range>6</range> <!-- If this weapon cam explode and the range. If not, just set it to 0--> <explosionRange>0</explosionRange> </attack> <!-- Specify if this object can be used when the user is in the recovery mode --> <availableOnRecovery>no</availableOnRecovery> </weapon> </weapons> </beyondar>
Element Description
name Weapon name that will be shown to the player.
id Weapon’s unique identifier.
maxAmount Max ammo that the weapon can store. Set to -1 for infinite.
amount Amount of ammo that the user will have when starting the mission with this weapon.
icon Image that represents the weapon.
iconBullet Path of the image that represents the bullet of the weapon
attack Description of the weapon attack.
- average Average damage dealt by the weapon.
- variation Damage variation for the weapon.
- range Range in which the weapon can be used (in metres).
availableOnRecovery Allow this weapon to be used in recovery mode. Set this value to "yes" or "no".
explosionRange If it is a explosive weapon, range of the blast radius.

This code shows how to create different weapons.

Defining the mod

Once we have the game elements (entities, objects and weapons) we can define the mod. To do so, create an XML file in the mod root folder called "descriptor.xml" (this name cannot be changed). Then we need to define the name, the icon, the author and the mod id.

<?xml version="1.0" encoding="utf-8"?>
<beyondar version="1.0">
	<mod>
		<!-- Icon that represents the mod -->
		<icon>other/survive_mode_icon.png</icon>
		<!-- Name of the mod -->
		<name>BeyondAR Creatures</name>
		<!--  Author -->
		<author>BeyondAR team</author>
		<!-- Unique identifier of the mod -->
		<id>beyondar.mod.2</id>
		<description>Some strange creatures from another dimension are invading Earth. Help your planet sending them back to their dimensions!</description>
		<version>0.1</version>
	</mod>
	<!-- Here the missions -->
</beyondar>
Element Description
mod Mod’s description.
icon Image that represents the mod.
name Name of the mod.
author Mod’s author.
id Unique identifier for the mod. The following format is recommended:
author.mod.mod_name

 

Mod missions

The code for the missions must be in the "descriptor.xml" file. This code will define the available missions and their goals, creatures, objects, etc.:

<missions>
	<mission>
		<!-- Name of the mission -->
		<name>Block the hole</name>
		<!-- Icon that represents the mission -->
		<icon>other/hole_blocked.png</icon>
		<!-- Type of the mission. There are 3 types: "select objective", "time" and "points" -->
		<type>select objective</type>
		<time>600</time>
		<!-- seconds -->
		<!-- A short description of the mission -->
		<description>Find the interdimensional hole used by the creatures to come to our world and block it!</description>
		<!-- If this element is present, the game will display a HTML before the game starts. Use this to 
			give an extended overview of the mission. Only plain HTML is allowed -->
		<introHtml>html/intro_1.html</introHtml>
		<!-- Define the message that will be showed if the user wins the game -->
		<winMessage>You blocked the hole! All the creatures have been sent back to their dimension.</winMessage>
		<!-- Define the icon that will be showed if the user wins the game -->
		<winIcon>other/hole_blocked.png</winIcon>
		<!-- Define the message that will be showed if the user loses the game -->
		<looseMessage>Noooo!!! The hole is still open!!! </looseMessage>
		<!-- Define the icon that will be showed if the user loses the game -->
		<looseIcon>other/hole.png</looseIcon>
		<!-- Image that represents the location to reach. This element is used on the mission type "select objective" -->
		<flagIcon>other/hole.png</flagIcon>
		<!-- Name of the location to reach. This element is used on the mission type "select objective" -->
		<flagName>Interdimensional hole</flagName>
		<!-- List of available entities for this mission (id). Different entities must be separated by "," (comma) -->
		<entitiesAvailable>berly_creature_1, dolm_creature_1, nimbik_creature_1, nontric_creature_1, tulu_creature_1, singy_creature_1, muck_creature_1, etaolo_creature_1, box_entity_1, box_entity_2 </entitiesAvailable>
		<!-- List of the default weapons of the user. Different weapons must be separated by "," (comma) -->
		<defaultWeapons>molecular_sword_weapon, wrap_pistol_weapon, light_bow_weapon</defaultWeapons>
		<!-- List of objects that the user carries by default. Different objects must be separated by "," (comma) -->
		<defaultObjects>energy_object_1,hole_blocker_object_1 </defaultObjects>
		<!-- Default lives at the beginning of the game -->
		<lives>3</lives>
		<!-- Maximum lives that a user can have -->
		<maxLives>10</maxLives>
		<!-- Default health of the user at the beginning of the game -->
		<health>100</health>
		<!-- Maximum health that the user can have. -->
		<maxHealth>150</maxHealth>
		<!-- Default shield points at the beginning of the game. -->
		<shield>25</shield>
		<!-- Maximum shield points that the user can have. -->
		<maxShield>100</maxShield>
		<!-- Respawn the entities that are destroyed -->
		<respawnEntities>no</respawnEntities>
	</mission>
</missions>
Element Description
missions Mission list.
mission Mission description.
name Name of the mission.
description  
introHtml If this element is present the game will display a HTML before the game starts. Use this to give an extended overview about the mission. Only plain HTML is allowed
icon Icon that represents the mission.
winMessage Define the message that will be showed if the user wins the game.
winIcon IDefine the icon that will be showed if the user wins the game
looseMessage Define the message that will be showed if the user loses the game.
looseIcon Define the icon that will be showed if the user loses the game.
type Mission type. There are three types: "select objective", "survive" and "points".
- "select objective": The player has to select a point in the map and try to reach that point.
- "survive". The player has to survive during a period of time. Use the tag <time> to define the time (in seconds).
- "points": The player has to reach a set score. Use the element to define the score needed to win.
flagIcon Image that represents the location to reach. This element is used on the mission type "select objective".
flagName Name of the location to reach. This element is used on the mission type "select objective".
time Time limit. If the game type is "survive" this tag is mandatory.
points Target score to reach. This element is used on the mission type "points".
entitiesAvailable List of available entities for this mission (id). Different entities must be separated by "," (comma).
defaultWeapons List of the default weapons of the user. Different weapons must be separated by "," (comma).
defaultObjects List of objects that the user carries by default. Different objects must be separated by "," (comma).
lives Default lives at the beginning of the game.
maxLives Maximum lives that a user can have.
health Default health of the user at the beginning of the game.
maxHealth Maximum health that the user can have.
shield Default shield points at the beginning of the game.
maxShield Maximum shield points that the user can have.
respawnEntities Respawn the entities that are destroyed.

This "descriptor.xml" shows a mod with three different missions.

Combining values

With imagination it is possible to create many kinds of objects, from the most popular (health, weapons, keys...) to troll objects (mines dropped by the entities when destroyed, poisoned medicine...). In future versions additional actions and elements will be added. Of course, if you have any idea or suggestion for the game, use this link to share them with us.

You can also find other combinations in our blog.

Images

The images used in the mod must follow a set of guidelines:

Images for Format Size (pixels) Notes
Entities PNG 256x256
128x128
64x64
256x256 recommended
Objects/weapons PNG 256x256
128x128
64x64
256x256 recommended
Bullet images PNG 256x256
128x128
64x64
128x128 recommended
Logos (mod or missions) PNG Square images with a maximum size of 256x256 128x128 recommended