Here you will find a guide on how to create new regions and how to perform the translation of original Habitat regions from their source files.

Creating a new region from scratch is pretty simple, all you need is a little imagination and a text editor of your choice!

First of all, we recommend reading this Region Design document written by Chip back in December 1987. It goes into more technical detail than we will be covering here and will give you a solid grounding in how a region works. We're going to keep it simple here though for the most part.

We recommend exploring the NeoHabitat world to get an idea of the kind of regions that already exist and the artwork available to you. Once you've got an idea, you have three options.

1. Draw a region outline using any method you feel comfortable with and get an idea of how you want it to look. You could go old school and put pencil to paper or use any image editing software of your choice.

The Habitat Region Design Worksheet as used in development

2. You can copy an existing regions JSON file and modify it.

3. Once you become more acquainted with things, you could create a region from scratch with nothing more than a text editor and experiment on the fly.

Break down what objects your region will consist of. For example, every region will require either a wall or a sky object and a ground object. What else do you want to add to make your region more interesting? An ATM? Door? Fountain? You can check out all the available classes here.

Currently, the fastest way to build a region is to copy pre-existing JSON for an object and copy it into your regions JSON file.

If you would like an empty region to use as a base, we have included an empty region JSON file in the repo aptly named "empty.json" which you can grab here. If you teleport to this region ingame, it'll look like this:

Say we would like to add a choke machine to this region, search the db folder using the class name of the object to find it. Here is an example of a Choke Machine object:

  {
    "ref": "item-choke.d9k1.empty",
    "mods": [
      {
        "y": 30,
        "x": 120,
        "type": "Coke_machine",
      }
    ],
    "type": "item",
    "name": "Choke Machine",
    "in": "context-empty"
  }

Lets break this object down so you know what each thing means. For the most part, the only things you'll often need to modify are the objects specific property values and the region/context the object will appear in but it's good to have an understanding of how an object is constructed.

This list follows the same order as the object, so although a couple of names are identical they have different meanings depending on where they are placed.

• ref - The unique identifier of this object in the database
• mods - The object mods. Object specific properties and values are listed here
• y - The items y-coordinate as displayed in Habitat
• x - The items x-coordinate as displayed in Habitat
• type - The items object class
• type - This identifies the object as an item as opposed to a context (the Elko name for a region)
• name - The objects name in the database
• in - The region/context this item will appear in

If you copy this example into your empty.json region file and recompile it, you should see it inworld like so:

That is pretty much all creating NeoHabitat regions consists of. Find an existing object in the other JSON files, copy it into your file and modify the properties as necessary in order to place/color it.

NeoHabitat makes testing your changes in real time simple. First of all, if you are in the region you wish to modify, exit it first and ensure no other avatars are in there. Do the following.

• SSH into your NeoHabitat VM
• cd /neohabitat/db
• If you wish to recompile just one region only type in make ./regionName.o or ./directory/regionName.o depending on where the file is located
• If you wish to recompile the entire object database type in make clean

Once you re-enter the region, your changes should appear. If they don't then please read below for some common issues you can experience with region creation.

It's also highly recommended to read the Region testing procedure section of our wiki for more indepth information on testing. Especially if you intend on submitting your new creations to the NeoHabitat repository.

Here are a few common issues to bear in mind when creating a region:

• Ensure your JSON is correct by using something like JSONLint.

• When recompiling your new region, ensure that nobody is currently inside it including yourself otherwise it will error out.

• When you modify an objects unique ref and recompile a region, there will still be an entry in the database for the objects old unique ref as the NeoHabitat server will not delete this for you. If you want to get rid of any old objects, issue a make clean command in the db folder to force a fresh compile.

• When you want to fill in the port_dir or town_dir for a region, you can write in UP, DOWN, LEFT or RIGHT and the NeoHabitat server will parse it for you. However, it will not be JSONLint compliant as you do not need to enclose the direction in quotation marks.

• Ensure that each object's ref is unique. We recommend using the following as a naming scheme: "item-objectClass.letterNumberLetterNumber.regionName" so if we had a door in a region named foon, the object ref for the door could be "item-door.n2m5.foon".

• When you add a connection to another region context, the direction you exit the region in will be different depending on your regions orientation. If you are holding a God tool and have the correct permissions set on your avatar, when you enter a region it will tell you which connections go in which direction on your clients screen.

• Remember that orientation not only refers to the direction a region is facing, but also an objects color or pattern and whether the object is flipped left or right. You can read this guide on how to color objects.

• To see the different styles and gr_states available to you for each object class, please check out this guide written by Chip that lists all of the variations at your disposal. If you use a value that isn't correct, your region will be glitchy and may not even load. If you experience any glitching, it's often due to an incorrect property value in one or more of the objects in your region JSON.

• Be sure to give your region a name and remember it will be seen when a user presses F7 on the ground.

If you would like help with your new region creations, please join the #geography channel on Slack

The old documentation describes super trapezoids on page 100 as "like a regular trapezoid, except that instead of using one of the standard color patterns, it carries its own color/pattern information with it. Additionally, this pattern may be larger and fancier than any of the standard ones, so we can create elaborate textile-like patterns of various sorts." This is essentially correct, but doesn't go into quite enough detail if you need to edit or create those patterns.

The important parameters for defining the pattern are pattern_x_size, pattern_y_size, pattern, and orientation. pattern is exactly 32 bytes, each holding four 2-bit color values. These are used in English reading order to the width and height specified by pattern_x_size and pattern_y_size, with extra bytes at the end being ignored.

[WILD] is set by orientation and [SKIN] can be set by each client independently as documented elsewhere. Blue and black are always blue and black.

The pattern is pattern_x_size + 1 bytes in width, or four times that many pixels if you prefer to think that way. Similarly, it is pattern_y_size + 1 lines tall. The client will tile to cover the available space.

Regionator is a tool that converts riddle format region files into JSON for use in Neohabitat. Riddle was the format used in Habitat for region creation and we have an archive of these files from the original Habitat world. Regionator is handy for translating these into something usable for our project.

To use Regionator you must have the following installed in your build environment:

• Python
• Python Package Index (aka PIP)
• PyParsing
• [PyYAML] (http://pyyaml.org/)

Ubuntu users can use the following commands to set up the necessary stuff for the operation of the Regionator.

sudo apt-get install python-pip

sudo pip install pyparsing pyyaml

Once these have been installed, change to the regionator directory if you aren't already there and type the following:

python app.py yourRegionName.rdl

Replacing "yourRegionName.rdl" with the name of the source file which should be in the same directory as regionator.

You now have a converted Riddle file in JSON format. You should always manually check the output however as regionator is currently incomplete and may parse certain fields incorrectly.