Guide: How to add a new zone

[marvalis]

Guide: Adding a new zone to the game by making an addon
Last update for b41

This guide is intended to help people make their first zone. It is not a complete guide to all the functions / tables / etc used in this code.
These are only the first few steps to get you started.

Step 1: Creating a new addon
First, we have to create a new addon.
This is done by making a folder in:

/game/addons

Let us create a new folder. The name has to start with "tome-" followed by the name of your addon:

tome-youraddonname

Inside this folder we make a file called init.lua

/game/addons/tome-youraddonname/init.lua

long_name = "The name of your addon"
short_name = "youraddonname"
for_module = "tome"
version = {3,9,41}
weight = 100
author = { "your name"}
homepage = "http://tome.te4.org/"
description = [[Describe your addon here.]]
overload = true
superload = false
hooks = false
data = false

You might wonder what all these things mean. The most important thing:

• short_name has to be the same as the folder name after "tome-"
• The version has to be the latest version. For example, {3,9,41} refers to beta 41. {3,9,42} might refer to beta 42.

Step 2: Creating your zone folder
Create a folder called overload:

/game/addons/tome-youraddonname/overload

Inside overload, create a folder called data

/game/addons/tome-youraddonname/overload/data

Inside data, create a folder called zone

/game/addons/tome-youraddonname/overload/data/zone

Finally, inside zone, make a folder with the name of your new zone:

/game/addons/tome-youraddonname/overload/data/zone/yourzonename

Step 3: Create your zone files

/game/addons/tome-youraddonname/overload/data/zone/yourzonename/zone.lua

Inside this file, you have to put something like:

Code: Select all

return {
	name = "yourzonename",
	level_range = {1, 15},
	level_scheme = "player",
	actor_adjust_level = function(zone, level, e) return zone.base_level + e:getRankLevelAdjust() + level.level-1 + rng.range(-1,2) end,
	update_base_level_on_enter = true,
	max_level = 1,
	width = 30, height = 20,
	decay = {300, 800},
	persistent = "zone",
	all_remembered = false,
	all_lited = true,
	day_night = true,

	min_material_level = function() return game.state:isAdvanced() and 3 or 1 end,
	max_material_level = function() return game.state:isAdvanced() and 4 or 2 end,

	ambient_music = "Rainy Day.ogg",

	generator =  {
		map = {},
		actor = {},
		object = {},
		trap = {},
	},
	levels = {},

	post_process = function(level)
	end,

	foreground = function(level, x, y, nb_keyframes)
	end,
}

It is best that you go look at other zones to see how they are generated. You can find examples by extracting the tome module and looking in:

game/module/tome/data/zones

Randomly generated maps will have to use a script. This can be found by extracting the game engine, and going to:
game/engines/te4/engine/generator

For static maps, you have to put your map in

/game/addons/tome-youraddonname/overload/data/maps/zones/yourzonename.lua

Static map generator code:

Code: Select all

	generator =  {
		map = {
			class = "engine.generator.map.Static",
			map = "zones/yourzonename",
		},
	},

You have to create 3 more files. In these files you have to put something like: load("/data/general/npcs/thieve.lua")
This is needed to load the right files to generate the map.

/game/addons/tome-youraddonname/overload/data/zone/yourzonename/npcs.lua

Data found in game/module/tome/data/general/npcs/

/game/addons/tome-youraddonname/overload/data/zone/yourzonename/grids.lua

Data found in game/module/tome/data/general/grids/

/game/addons/tome-youraddonname/overload/data/zone/yourzonename/traps.lua

Data found in game/module/tome/data/general/traps/

/game/addons/tome-youraddonname/overload/data/zone/yourzonename/objects.lua

For a zone in the West, use: load("/data/general/objects/objects-maj-eyal.lua")
For a zone in the East, use: load("/data/general/objects/objects-far-east.lua")

Step 4: Putting your zone on the world map
You have to edit two files:

data/maps/wilderness/eyal.lua
data/maps/zones/wilderness/grids.lua

Copy these files to your addon:

/game/addons/tome-youraddonname-overload/data/maps/wilderness/eyal.lua
/game/addons/tome-youraddonname/overload/data/maps/zones/wilderness/grids.lua

Make a new entity in grids.lua. You can change your own RGB values etc.

Code: Select all

newEntity{ base="ZONE_PLAINS", define_as = "YOURZONENAME",
	name="the name that is displayed",
	color={r=250, g=250, b=250},
	add_displays={class.new{image="terrain/road_going_right_01.png", display_w=2}},
	change_zone="yourzonename",
}

In eyal.lua, add the following:

Code: Select all

defineTile('yourzonename', "YOURZONENAME")

Then put [[yourzonename]] somewhere in the map grid.

[mertonhobbit]

This is a great start. But could we get this updated for 1.0.0, and generally corrected?

As far as I know the only 1.0.0 update is to change the version number in init.lua to 1,0,0.

There seem to be a number of errors, though, in this walkthrough which will keep 90% of people from even making a blank zone. At least, I followed these instructions exactly, and couldn't get it to work. I also tried the steps below, and it still didn't work. "Lua Error: /engine/utils.lua:115: bad argument"

Maybe we can repeatedly tell people how to unzip teaa, etc., files, since they are very odd. (I presume rename as zip and then double-click?)

Is it also possible to carry the red-text aspect of "myzone" all the way through the doc, so it's obvious what has to be filled in and what does not?

In step 3, could you please be explicit about what has to go into npcs.lua, grids.lua, traps.lua? Presumably not all thieve.lua? What is the minimal file I need?--do I need to change anything at all if I don't want? Also, I think that ALL the references to "zone" in the directory structures should be "zones". Is that right?

In step 4, please be explicit about where the files are to be copied from--please start the directory structure before "data/maps", because there are so many things named the same thing but in different directories that I can't keep them straight.

Also, in step 4, I think the second source directory is wrong: it's not data/maps/zones/wilderness/grids.lua, but data/zones/wilderness/grids.lua. That also means the destination directory is wrong, I think.

Are the yourzonename and YOURZONENAME really distinguished by all caps in the latter case?

Finally, is it possible to have a snapshot of what a final directory structure should look like? Something like this? (If it's correct.)

Screen Shot 2013-02-20 at 2.26.04 AM.png (87.36 KiB) Viewed 1790 times

Also maybe mention that one turns on this addon just by going to the "addon" button below "load game" or "view high scores" and toggling it--although all addons seem to be on by default.

Sorry for critiquing the post, but I'm afraid that I can't get it to work as it stands, or with my tinkering, and I would love some help for me, as well as for everyone who comes after!

Thanks!