VoxeLibre/mods/MAPGEN/mcl_villages/API.md

mcl_villages

When creating buildings or farms for use with this mod, you can prevent paths from crossing areas by using the mcl_villages:no_paths block. You may need to stack them 2 high to prevent all paths. After the village paths have be laid this block will be replaced by air.

Building Interfaces

Parameter

All of the following functions take a table with the following keys.

Mandatory

name

The name to use for the object.

mts

The path to the mts format schema file.

Optional

yadjust

Y axis adjustment when placing the schema. This can be positive to raise the placement, or negative to lower it.

If your schema does not contain a ground layer then set this to 1.

no_ground_turnip

If you don't want the foundation under the building modified, you can disable the ground turnip by setting this to true.

Mainly useful for small thing such as lamps, planters, etc.

no_clearance

If you don't want the area around and above the building modified, you can disable the overground clearance by setting this to true.

Mainly useful for small thing such as lamps, planters, etc.

mcl_villages.register_lamp(table)

Register a structure to use as a lamp. These will be added to the table used when adding lamps to paths during village creation.

mcl_villages.register_bell(table)

Register a structure to use as a bell. These will be added to the table used when adding the bell during village creation.

There is 1 bell per village.

mcl_villages.register_well(table)

Register a structure to use as a well. These will be added to the table used when adding the wells during village creation.

The number of wells is calculated randomly based on the number of beds in the village. Every 10 beds add 1 to the maximum number.

e.g. 8 beds == 1 well, 15 beds == 1 or 2 wells, 22 beds == 1 to 3 wells, etc.

mcl_villages.register_building(table)

Register a building used for jobs, houses, or other uses.

The schema is parsed to work out how many jobs and beds are in it.

If you are adding a job site for a custom profession then ensure you call mobs_mc.register_villager_profession before you register a building using it.

If a building doesn't have any job sites or beds then it may get added during the house placement phase. This will simply add another building to the village and will not affect the number of jobs or beds.

Additional options

The mcl_villages.register_building call accepts the following optional parameters in the table.

min_jobs

A village will need at least this many jobs to have one of these buildings.

This is used to restrict buildings to bigger villages.

max_jobs

A village will need less that or equal to (<=) this many jobs to have one of these buildings.

This is used to restrict buildings to smaller villages.

num_others

A village will need this many other job sites before you can have another of these jobs sites.

This is used to influence the ratio of buildings in a village.

is_mandatory

This ensures that each village will have at least one of these buildings.

mobs_mc.register_villager_profession(title, table)

TODO this should be somewhere else.

This API call allows you to register professions for villagers.

It takes 2 arguments.

1. title - The title to use for the profession.

This mus be unique; the profession will be rejected if this title is already used.

1. Record - a table containing the details of the profession, it contains the following fields.

   1. name: The name displayed for the profession in the UI.
   2. texture: The texture to use for the profession
   3. jobsite: the node or group name sued to flag blocks as job sites for this profession
   4. trades: a table containing trades with 1 entry for each trade level.

You can access the current profession and job site data in mobs_mc.professions and mobs_mc.jobsites.

mcl_villages.register_on_village_placed(func)

This function allows registering functions to be called after a village is laid out.

Note that the village may not be completed as the building post processing is non-deterministic to avoid overloading the server.

settlement_info is a table containing data for all the buildings in the village. The bell is always the first entry in the table.

blockseed is the block seed for the chunk the village was generated for. Villages can extend outside of this chunk.

local function my_village_hook(settlement_info, blockseed)
	minetest.log("The village has " .. #settlement_info .. " buildings in it!")
end

mcl_villages.register_on_village_placed(my_village_hook)

mcl_villages.register_on_villager_spawned(func)

This function allows registering functions to be called after a villager is placed as part of village generation.

villager_ent is the entity created by minetest.add_entity.

blockseed is the block seed for the chunk the village was generated for. Villages can extend outside of this chunk.

local function my_villager_hook(villager_ent, blockseed)
	local l = villager_ent:get_luaentity()
	minetest.log("The villager's id is " .. l._id)
end

mcl_villages.register_on_villager_spawned(my_villager_hook)

Farm Interface

These functions aid creating crops for use use in farms placed during village generation.

mcl_villages.get_crop_types()

This allows checking what crop types are supported.

Currently they are: grain, root, gourd, flower, bush, tree.

Placement of gourds should take in to consideration the way they fruit.

mcl_villages.get_crops()

Returns a table containing all registered crops.

mcl_villages.get_weighted_crop(biome, crop_type, pr)

Gets a random crop for the biome and crop type.

mcl_villages.register_crop(crop_def)

Registers a crop for use on farms.

crop_def is a table with the following fields:

• node the name of the crop node to place. e.g. mcl_farming:wheat_1.
• crop_type the type crop. e.g. grain
• biomes a table containing the weighting to give the crop.
  • Supported biome values are:
    • acacia
    • bamboo
    • desert
    • jungle
    • plains
    • savanna
    • spruce
  • If you leave a biome out ot he definition then the crop will not be available in that biome. e.g.

mcl_villages.register_crop({
	type = "grain",
	node = "mcl_farming:wheat_1",
	biomes = {
		acacia = 10,
		bamboo = 10,
		desert = 10,
		jungle = 10,
		plains = 10,
		savanna = 10,
		spruce = 10,
	},
})

Creating farms with replaceable crops

To create a farm that will utilize registered crops you follow the basic process for creating a farm, but you leave out the crops.

Once you have your farm constructed then instead of placing crops you place blocks named mcl_villages:crop_* over the dirt in the farm.

Each crop type has 8 blocks that can be used for it. This allows, but does not guarantee, variety of crops in a farm.

Each of the crop tiles has an image of a entity that it represents. This image is representative, not explicit.

i.e. The root crop tiles have an image of a carrot on them, but they will be swapped for a random root crop, not always carrots.

Each specific node will be replaced by a single item.

e.g. if you use mcl_villages:crop_root_1 and mcl_villages:crop_root_2 in your farm then all there will be at most 2 types of root crops on the farm.

It is random, so both types may get replaced by the same crop.

Remember that gourds affect 5 nodes when they crop; a good farmer won't plant anything on the 4 nodes a fruit wil form and your farm should not do that either.

Once you have saved the schema for your farm you register it with the building interface.

e.g.

mcl_villages.register_building({
	name = "my_farm",
	mts = schem_path .. "/my_farm.mts",
	num_others = 3,
})

When a village is generated there will be a chance your farm will be placed, any crop blocks will be replaced by biome appropriate crops.

If a crop cannot be found for a crop type in a biome, then a default will be used. This ensure all farming blocks are full, ven if it's al the same crop.

The default is wheat.

Village Layout

There are two methods for layout out villages, circle layout is more likely to be used for small villages and grid for large villages.

The circle layout uses circles (surprise) to calculate if buildings overlap. It creates fairly widely spaced layouts.

The grid layout uses a predetermined grid layout to positions buildings and uses AreaStore to adjust building position if there are collisions.

The predetermined grid is below, position 0 is the bell, the other numbers are the order of placement.

48	41	33	25	29	37	45
40	17	13	9	11	15	43
32	19	5	1	3	22	35
28	23	7	0	8	24	27
36	21	4	2	6	20	31
44	16	12	10	14	18	39
46	38	30	26	34	42	47