From Arianne
Jump to navigation Jump to search

Of course you have already read:

Ok, and I assume that you can write or at least read xml.

Modify world.tmx

Now make sure if your map is new that world.tmx shows it by adding a new tileset with your map image. This step is just for your mental wellness. Stendhal doesn't use world.tmx.

Create a map file

If you are adding a zone for a new major area, create the file data/conf/zones/<area>.xml with the following:

<?xml version="1.0" encoding="UTF-8"?>
   ** Load zones. Written from left to right and from top to bottom.
   ** Please respect it!


Then edit the file data/conf/zones.xml and add a relevant entry (in alphabetical order for normal areas):

 <group uri="zones/<area>.xml"/>

To enable a zone in the server, edit the file data/conf/zones/<area>.xml and add an entry (in the appropriate level/top-down/left-right order), giving it the zone name and map tmx file to use:

 <zone name="int_myarea_mylocation" file="interiors/myarea/mylocation.tmx"/>
 <zone name="0_myarea_mylocation" level="0" x="100000" y="200000" file="Level 0/myarea/mylocation.tmx"/>

In the case of non-interior zones, the level and x/y coordinate should also be included in the <zone> element (setting them in the tmx file has been deprecated). For interior zones, the level xml attribute should not be set (for now). The coordinate starts at the top-left corner, and should align against (but never overlap) other zones in the same level.

If the new zone is outside, or otherwise should follow the normal daylight cycle, add a coloring method definition to it, like this:

 <zone name="0_myarea_mylocation" level="0" x="100000" y="200000" file="Level 0/myarea/mylocation.tmx">
   <parameter name="color_method">time</parameter>

About other possible coloring methods for maps, see Lights and Color.

Most zones can be configured just using this xml file. However, there are currently some things, such as NPC's that need special handling. If you need to do custom zone configuration, create one or more new java source file(s) at src/games/stendhal/server/maps/<area>/<base-location>/<entity>.java. The <area>/<base-location> path would essentially be the same as your .tmx file uses. In case where locations have been split due to size (like _nw, _ne, _s, _n, etc), only the base location name is used.

Ideally this would be one file per independant entity created (so they can be enabled/disabled separately).

Some (ficticious) examples for the new convention of tmx path to java filename are:

interiors/orril/old_cabin.tmx -> .../maps/orril/old_cabin/
Level 0/ados/rock.tmx -> .../maps/ados/rock/
Level -1/ados/caves_e.tmx -> .../maps/ados/caves/
Level 0/nalwor/river_se.tmx -> .../maps/nalwor/river/
Level 0/nalwor/river_se.tmx -> .../maps/nalwor/river/
Level 0/nalwor/river_sw.tmx -> .../maps/nalwor/river/
Level 0/semos/forest_n.tmx -> .../maps/semos/forest/

Open the file and make sure that it looks like this:

package games.stendhal.server.maps.myarea.mylocation;

import java.util.Map;
import games.stendhal.server.StendhalRPZone;
import games.stendhal.server.config.ZoneConfigurator;

public class MyEntity implements ZoneConfigurator {
     * Configure a zone.
     * @param       zone            The zone to be configured.
     * @param       attributes      Configuration attributes.
    public void configureZone(StendhalRPZone zone, Map<String, String> attributes) {
        // Add/configure entity to "zone", using optional configuration "attributes"

For each custom configuration code class, add appropriate "<configurator>" entries in your "<zone>" element, using the fully qualified package/class name of your java classes:

 <zone name="int_myarea_mylocation" file="interiors/myarea/mylocation.tmx">
  <configurator class-name="games.stendhal.server.maps.myarea.mylocation.MyEntity"/>

Now once it is added, test the result by starting server.

Populating zones

Now open again the file and let's start adding code to configureZone(), or a method called by it. Most usual things we are going to add to a zone are NPC, and special items.

Adding Items

See How to add items to Stendhal and How to know graphics specifications

Adding Portals

A portal is a door to another place. It can be used to go up and down stairs, or to teleport player to other places or simply to enter a building. Whenever you encounter something that engine challenges you about how to do ( for example cross under a brigde or pass under a castle door ) you can solve it using portals.

There are several types of portals:

  • Portal added using xml
  • One way portal added using xml
  • Stairs portals added using tiled
  • House Door portals added using tiled

A portal is just the generic portal. It works for almost everything you can imagine.

Portals are created by adding a entries to your zone in zones.xml. For example creating a portal to an internal building entrance which is at 1 12 inside the building (and the outer entrance to go in is at 10 15) might look like:

 <zone name="int_myarea_mylocation" file="interiors/myarea/mylocation.tmx">
    <portal x="1" y="12" ref="entrance">
     <destination zone="0_myarea_city" ref="mylocation_entrance"/>

 <zone name="0_myarea_city" Level="0" x="500000" y="500000" file="Level 0/myarea/city.tmx">
    <portal x="10" y="15" ref="mylocation_entrance">
     <destination zone="int_myarea_location" ref="entrance"/>

The ref attribute of a portal should be a name unique to the zone it is in (and meaningful). This value has a corresponding reference via the <destination> ref name. You are responsible for correctly assigning the ref names of each portal.

A one way portal is a portal that only exists as endpoint, so none can use the portal to move back to the origin. For one way portals, there is no <destination> sub-element, as they don't go anywhere. Also, you need to provide a non-default implementation:

  <portal x="11" y="44" ref="my_exit">
   <implementation class-name="games.stendhal.server.entity.mapstuff.portal.OneWayPortalDestination"/>

The House door portal is a special type of portal that automatically creates all the portals and areas needed to add a house to that zone with its entrance on point where the portal is. In tiled/tileset/logic/portals.png it's the one with the door on it. Add it to the 'city' type map where you want the house entrance. Please see the tiled tutorial.

Finally the stairs portals also automate the creation of stairs between two areas. It is very important that the portals ( both ends ) are exactly on the same position but on different levels. Position means absolute position. Also, due to current implementation, be careful not to place omni-directional stair portals at the same exact location between adjacent levels if they're not meant to be linked, as they might inadvertantly be linked. Directional stairs are safer and only link with the level they go toward. The the tiled tutorial covers this in more detail.

Condition and Action Portals

Portals are being refactored to allow combinations of conditions and actions in a very similar way to NPCs. In fact, you can use the same conditions and actions. The full list is found in and

A portal which you can put a Condition and / or action to is called a ConditionAndActionPortal. You don't have to set both a condition and an action.

Implement them like this:

 <portal x="64" y="117" ref="entrance">
  <destination zone="-1_semos_chasm_n" ref="exit" />
  <implementation class-name="games.stendhal.server.entity.mapstuff.portal.ConditionAndActionPortal">
   <parameter name="condition">new PlayerHasItemWithHimCondition("special magical thingy", 10)</parameter>
   <parameter name="action">new DropItemAction("special magical thingy", 10)</parameter>
   <parameter name="rejected">You need 10 of the special magical thingies.</parameter>

You can use NotConditions:

 <portal x="65" y="13" ref="entrance">
  <destination zone="-1_semos_chasm_w" ref="exit" />
  <implementation class-name="games.stendhal.server.entity.mapstuff.portal.ConditionAndActionPortal">
   <parameter name="condition">new NotCondition(new PlayerHasPetOrSheepCondition())</parameter>
   <parameter name="rejected">To get into the evil chasm you must bring a sacrificial animal</parameter>

You can do more than one action by using MultipleActions and list the actions for it, and combine Conditions with an AndCondition, listing the conditions for it. The syntax is slightly different than with NPCs, please note these extra [ ] surrounding the list. This is due to a bug in groovy.

   <portal x="37" y="16" ref="example1">
     <destination zone="int_semos_zone" ref="choice_floor_1" />
     <implementation class-name="games.stendhal.server.entity.mapstuff.portal.ConditionAndActionPortal">
       <parameter name="condition">new AndCondition([new NotCondition(new PlayerHasItemWithHimCondition("claymore")) , new LevelLessThanCondition(100)])</parameter>
       <parameter name="action">new MultipleActions([new IncreaseXPAction(100), new EquipItemAction("claymore")])</parameter>

The destination settings and references are all as normal. You can still set other attributes like a reject message and hidden from minimap, as in some of the examples above.

Adding NPCs

See Stendhal NPC Coding

Congrats you have populated your new zone.

Back to the Stendhal main page