Editing Map Editor Events

== Introduction ==

Quests and dialog in-game are created through Tuxemon's event system. All events in the Tuxemon event system are stored as objects in each individual map file using a TMX map editor like the free and open source [http://www.mapeditor.org/ Tiled map editor]. This way it is possible to quickly and easily add new events such as dialog, trainer battles, etc. to each map.

There are two components to an event: '''conditions''' and '''actions'''. A '''condition''' is a certain condition or set of conditions such as ''"player at location"'' that must be true in order to execute an action or group of actions. An '''action''' is an action such as ''"display dialog"'' or ''"start battle"'' that will be executed in the event that all of its conditions are true.

Try loading an existing map under <code>resources/maps</code> in Tiled map editor and see how existing events are set up as an example. Looking at existing maps is a great way to get started.

== Creating an event ==

Events are defined in an '''"Object Layer"'''. Click on the '''"Objects"''' tab and click the http://www.tuxemon.org/images/wiki/tutorial/tiled-new-obj.png icon to create a new Object Layer and name it "Events".

http://www.tuxemon.org/images/wiki/tutorial/map-tutorial11.png

You create an event by adding an object on the "Events" layer and specifying it's type using a TMX map editor like Tiled. There are three types of events in Tuxemon: "init", "event", and "interact". Init types only run once when the map is loaded. Event types run every event loop. Interact types run when a player is next to a location with the event and presses the action button.

== Event Conditions ==
Event conditions can be defined within a map editor such as Tiled. After creating an event, add a custom property and name it "'''cond1'''". You can have any number of conditions tied to a single event.

Each condition property's values are formatted in the following way separated by spaces:

<code><operator> <condition> <parameters></code>

* '''operator''': Whether or not this condition should be true. Can be either <code>is</code> or <code>not</code>.
* '''condition''': The name of the condition to check for. Check the [[Condition Reference]] for a list of available conditions.
* '''parameters''': The condition's parameters such as tile position, etc.. Check the [[Condition Reference]] for a list of available condition parameters.

Here are some example event conditions:

http://www.tuxemon.org/images/wiki/tutorial/condition_example.png

=== Event Actions ===
Event actions can be defined within a map editor such as Tiled. After creating an event, add a custom property and name it "'''act1'''". You can have any number of actions tied to a single event.

Each action property's values are formatted in the following way separated by spaces:

<code><action> <parameters></code>

* '''action''': The name of the action to execute. Check the [[Action Reference]] for a list of available actions.
* '''parameters''': The action's parameters such as tile position, etc.. Check the [[Action Reference]] for a list of available action parameters.

Here are some example event actions:

http://www.tuxemon.org/images/wiki/tutorial/action_example.png

== Example ==

Here is an example of how you would define an event using Tiled:  

http://www.tuxemon.org/images/wiki/tutorial/event_example.png

== Advanced Events ==
This section describes some more advanced ways you can use events in Tuxemon and even ways you can create brand new custom actions and conditions to use in Tuxemon.

=== Using multiple events together ===
The best way to string multiple events together is using the <code>set_variable</code> action and the <code>is variable_set</code> condition. These two kinds of events will let you set arbitrary game variables that you can use for any purpose. One example of this might be changing the dialog of NPC after you defeat them in battle.

Here's an example of what this might look like with two separate events:

'''event1'''  

> <code>cond1</code> <code>not variable_set npc_defeated:yes</code>  
> <code>act1</code> <code>dialog It's time to BATTLE!</code>  
> <code>act2</code> <code>start_battle 1</code>  
> <code>act3</code> <code>set_variable npc_defeated:yes</code>  

'''event2'''

> <code>cond1</code> <code>is variable_set npc_defeated:yes</code>  
> <code>act1</code> <code>dialog Arrrggg! You beat me!!</code>

=== Custom actions and conditions ===
If a built-in action or condition doesn't exist on the [[Event Reference]] page for something you'd like to do, Tuxemon provides a way to easily create your own custom actions and events. Creating custom events requires some Python programming knowledge.

For a more in-depth guide to creating your own custom event actions or conditions, check out the [[Creating Custom Events]] page. 

== Map Properties ==

In addition to event objects, maps may contain special properties acting as map settings. In Tiled they are accessed by selecting Map Properties from the Map menu, then adding the property and value under the Custom Properties section of the Properties list. Available map properties include:

* <code>edges</code> The edge type of the map. When left out black borders are used. "clamped" will limit the camera within the world boundaries. "stitched" may later be supported to connect opposite edges of a map seamlessly.

== Event Reference ==

For a list of all available actions and conditions in Tuxemon, check out the [[Event Reference]] page.