NC Rift — Configuration guide

This guide explains what to fill in to make the resource work on your server and what every option does. Everything is changed from the config: there is no need to touch the code.

• The config files are config.lua and the config/ folder.
• Your own changes go in config_custom.lua, which you create by copying config_custom.lua.example. It is loaded after all the other files and changes only what you write: this way, when you update the resource, you lose nothing.
• At start the server console prints config check: N warning(s) and a warning for every error:
  • a misspelled key;
  • a wrong type (for example a text where a number is needed);
  • a reference that does not exist (for example a zone that uses a mob that is not there).

The resource starts anyway. Fix until you read 0 warning(s).

• Distances are in metres, times in milliseconds (...Ms), in seconds (...Sec, seconds) or in minutes (...Min). Chances go from 0 to 1 (0.25 = 25%).
• Coordinates are written as in FiveM: vec3(x, y, z) or vec4(x, y, z, heading).

1. Quick start: what you must fill in

Quick test in game, after the start:

• /rift_devtest checks every model, animation and particle of the config and writes the result to data/devtest.txt;
• /rift_spawn <type> creates mobs in front of you;
• /rift_open <rift> opens a rift in front of you;
• /rift_random opens a random rift right now;
• /rift_boss <boss> summons a boss.

2. Recipes (the most common cases)

Adding a monster zone

In config/zones.lua (or in config_custom.lua, written as Config.Zones.my_zone = { ... }):

my_zone = {
    shape    = 'circle', center = vec3(100.0, -200.0, 30.0), radius = 150.0,
    zMin     = -20.0, zMax = 200.0,        -- height where the zone counts
    interior = false, indoor = false, bucket = 0,
    mobs     = { 'skeleton_warrior', 'ghost' },   -- keys of Config.Mobs
    levels   = { 1, 5 },                          -- minimum and maximum level
    density  = 6,                                 -- mobs alive together in the zone
    day = 1.0, night = 1.5,                       -- density x by day / by night
    red = false, safe = false,
    points   = {},                                -- empty = random point on valid ground
},

Adding a fixed rift

In config/rifts.lua, inside Config.Rifts:

my_rift = {
    zone = 'my_zone', pos = nil,       -- pos = vec3(...) for a fixed point, nil = a point of the zone
    level = 3, hp = 1500, size = 1.0,
    spawn = { types = { 'skeleton_warrior' }, everySec = 20, max = 6 },
    respawnSec = 600,                  -- destroyed: it opens again after 10 minutes
    boss = nil, blackout = false,
    resist = { melee = 1.0, bullet = 1.0, fire = 1.0 },
    loot = nil,                        -- nil = Config.Rewards.default.rift
},

The name in the 9 languages goes in locales/<language>.lua, under the key rift_name_my_rift. Without this key the id is shown.

Rifts that show up at random

In config/rifts.lua, Config.RandomRifts.list: { rift = 'my_rift', zones = { 'my_zone', 'other_zone' }, weight = 1 } or, with your own points, { rift = 'my_rift', points = { vec4(x, y, z, heading), ... }, weight = 1 }. The rift uses the data of Config.Rifts.my_rift (health, mobs, loot) and appears at one of those points or at a point of one of those zones. With randomOnly = true in Config.Rifts.my_rift that rift opens only at random, never at start.

Coordinates with an imprecise z

The z of the config coordinates (pos of the rifts, points of the random rifts, arena center of the bosses) can be a few metres wrong: the first player who passes near asks the game where the ground is and the server moves the rift (or the boss) there. The answer stays in data/ground.json, so it happens only once. It is tuned with Config.Rift.groundFix; for a rift or a boss on a roof, in an MLO or on an island high up set ground = false.

Adding a boss

In config/bosses.lua:

• mob = a type of Config.Mobs;
• arena.center = your coordinates;
• spawn.mode:
  • 'timer' = at start and then respawnMin minutes after death;
  • 'admin' = only with /rift_boss;
  • 'event' = only from the SpawnBoss export.

Giving items as a reward

In the loot field of a mob, a boss or a rift, or in Config.Rewards.default:

loot = { items = { { item = 'bandage', min = 1, max = 2, chance = 0.3 } },
         money = { { account = 'cash', min = 50, max = 120, chance = 1.0 } },
         itemsChance = 0.3, moneyChance = 0.8 },

With ox_inventory you use the names of ox_inventory/data/items.lua. itemsChance / moneyChance (optional, from 0 to 1) are the chance that the mob drops items / money at all: with itemsChance = 0.3 only 3 mobs out of 10 drop items, and for those each line rolls its own chance. Without = always. In the editor they are the "Item drop %" and "Money drop %" fields of the preset.

A new monster type

Copy a mob of config/mobs.lua with a new key and change model, hp, damage, spells, xp. Mod peds and props go in config_custom.lua. Then add the key to the mobs of a zone. The name in the 9 languages goes in locales/<language>.lua, under the key mob_name_<key>.

3. All the options

3.1 config.lua — general

3.2 Performance (Config.Perf)

3.3 World

3.4 Mob brain (Config.Ai)

3.5 Damage (Config.Damage)

3.6 Rewards, stealth items, EXP

3.7 Visuals

3.8 Zones (Config.Zones.<id>)

3.9 Mobs (Config.Mobs.<type>, Config.MobLevels, Config.Packs)

3.10 Spells (Config.Spells.<id>)

Common fields:

• kind: 'fire', 'grab', 'roar', 'projectile', 'heal', 'invis', 'leap' or 'summon';
• warnMs: warning before the effect (the player has time to move);
• anim: animation of the casting mob;
• fx: particles;
• sfx: sounds in place, { cast = {...}, fly = {...}, impact = {...} } (files in web/sounds/, one at random): cast at the hand when it starts (shot, bow), fly while the projectile flies or the meteor falls, impact when it lands;
• range / minRange: maximum / minimum distance from the target;
• radius: area hit (0 = only the target);
• damage: damage at level 1;
• cooldownMs: cooldown at level 1;
• minLevel: minimum mob level to use the spell;
• needSight: the mob must see the target;
• status: effect left on the player.

The states burn, shock, freeze and slow are tuned in Config.SpellStatus. Config.SpellFx tunes the object that carries the trail of the projectiles and the distance of the camera shake.

3.11 Rifts (Config.Rifts.<id>, Config.RandomRifts)

3.12 Bosses (Config.Bosses.<id>)

4. What to change in the open code (open/)

The functions in open/ are made on purpose to be changed by you. The rest of the resource calls them, and if one throws an error nothing gets stuck.

Exports and events for other resources: see README.md → "Exports and events".