Quick Start & Modding Basics

Types of mods

Nebuchadnezzar supports three type of mods:

All mods types have the same data structure and provides the same functionality. They only differ in the way how to obtain them and where are stored.

Local mods

• These mods can be downloaded from any sources.
• These mods are supported on all distributions platforms builds (Steam, Gog and any future platforms).
• They should be put to [user data folder]/mods/

Steam Workshop mods

• These mods can be downloaded through the Steam Workshop system.
• For Steam builds only.

Developer mods

• Special variant of local mods.
• Used to develop and upload your mods.

What is moddable?

Everything except the tutorial, guide, UI and fonts. That means, you can create or edit goods, production chains, buildings, monuments, maps, missions or even ther whole campaigns and more.

Mod files structure

Each mod is single folder.

• Name of the folder determines the name of the mod.
• This name is then used to reference this mods from other mods.
• You should ensure that your mod name will be unique

Each mod has two types of files. These are:

• Definition files - They contains information about new entities or changes in the existing entities.
• Data files - Data which are referenced by the definition files. Typically sprite images.

Definition files

Definition files, in short def files, are written in Lua language.

• It means you can use most of Lua language features. Such like variable, aritmetic operations or functions.

Atoms

The basic unit of the game is Atom.

• Each entity in the game is defined as a atom. For example single atom is building, walker, employee, mission, city, goods etc.
• Each atom has properties from which some are obligatory and some are optional. Depending on a type of the atom.
• Atoms are defined in the definition files.
• Type of the atom is based on the name of definition file.
  • For example if you want to create or edit decoration buildings, you have to put your atoms to def/build_decor.lua definition file
  • Check base mod in game data for definition files names.

Atom name

• Atom name is the most imporatant property of each atom.
• It has form mod_name::raw_name
  • mod_name part is important because it allows us to unequivocally reference atoms from other mods
  • raw_name is then name identifying atom within its mod

Atoms functions

There are 5 functions for creating or editing atoms.

Create atom

To create new atom, use function atom (name, data)

Example

atom ('surface.desert.soil.1',
{
    grid = 'grid.desert',
    neighbor_grid = 'grid.soil',
    neighbor_transition = 1,

    masque = {{"images/surface/desert_soil/desert_soil_1.png"}},
    grass = grass,
    grass_ending = grass_ending
})

name parameter

• Name of the created atom.
• Notice that it does not have the mod_name part.
• It's because you don't have to use it when creating atom, because it's provided automaticaly based on the mod.

data parameter

• Contains all properties of the atom.
• Has form of Lua table, where key is name of a property and value is the value of the property.

parent data parameter

• atom functions may also take up to two parent data tables atom (name, [pd1], [pd2], data)
• Example

caravan_leader_base = {
    masque = {{"images/walker/caravan/leader/leader_#.png", 32}},
    offsets = {{24, 55}, {24, 55}, {24, 55}, {24, 55}},
    speed = caravan_speed,
    slave_offsets = {7, 16},
}

atom ('walker.caravan.wine', caravan_leader_base,
{
    info_goods = 'goods.wine',
    slave_walkers = {'walker.donkey.wine', 'walker.donkey.wine'},
})

• Then the created atom takes properties from the parent data and add (or override by) properties defined in the data table.

Replace atom

To replace existing atom in other mod use function atom_entire (name, data)

Example

atom_entire ('base::walker.donkey.grapes',
{
    masque = {{"images/walker/caravan/donkey_grapes/donkey_grapes_#.png", 32}},
    offsets = {{27, 53}, {27, 53}, {27, 53}, {27, 53}},
})

name parameter

• In this case the name is the name of atom we want to replace.
• So here we have to use the whole name including the mod part, because we are replacing atom from other mod.

data parameter

• All data of the original atom are replace by these data.

Replace atom property

To replace property in existing atom in other mod use function atom_property (name, data)

Example

atom_property ('base::walker.transport.full.clay',
{
    masque = {{"images/walker/transport/clay/full/full_transport_clay_#.png", 64}},
    offsets = {{17, 35}, {15, 36}, {29, 40}, {29, 36}},
})

name parameter

• Name of atom we want to replace property in.
• Here we also have to use the whole name including the mod part.

data parameter

• All properties stated in the data are used to override corresponding properties in the original atom.
• Rest of the properties in the original atom stays the same.

Extend atom property

To extend property in existing atom in other mod use function atom_extend_property (name, data)

Example

atom_extend_property ('base::mission.nz.13',
{
    allowed_templates = {'mn_template.my_custom_temple'},
})

name parameter

• Name of atom we want to extend property in.
• Here we also have to use the whole name including the mod part.

data parameter

• All properties stated in the data are used to extend corresponding properties in the original atom.
• All properties must be type of array, otherwise the file is invalid.

Inherit and create atom

To create new atom by inheriting from existing use function atom_inherit (name, parent, data)

Example

atom_inherit ('event.intro.my_custom_mission', 'base::event.intro.nz.1',
{
    image = "images/ui/events/my_custom_mission.png",
})

name parameter

• Name of atom we want to create.

parent parameter

• Name of atom we want to inherit from.
• Use the whole name including the mod part if it's from other mod.

data parameter

• All properties stated in the data are used to override corresponding properties from the parent data.
• Rest of the properties is copied from the parent.

Atom reset property

• atom_reset_property() is a special function usable when rewriting some atoms property and you want to revert the property to its default value
• For example remove some objectives from the mission.

Example

atom_property ('base::mission.nz.13',
{
    target_population = atom_reset_property(),
})

Referencing atom

Atom properties often reference other atoms or array of atoms.

• To reference an atom within the mod, use it's raw part of name only.
• To reference an atom from other mod, use the whole name including the mod part.

Creating mod

Prepare environment

First of all you need to prepare environment.

Enable developer console

You will need to enable developer console.

• Locale vars.ini file containing all game settings, even the hiddne one.
• File is located in Nebuchadnezzar user data
  • On Windows it's Documents\NeposGames\Nebuchadnezzar
  • On Linux it's typically /home/[user]/.local/share/NeposGames/Nebuchadnezzar
• In the vars file change line v_console 0 to v_console 1

Create mod folder

And now it's time to start to create the mod.

• In developer mods folder create folder with the name of you mode.
• Inside this folder create another folder with the same name.
• Your data structure should then looks like this [Nebuchadnezzar user data]/mods_developer/my_first_mod/my_first_mod/
  • User data Windows: Documents\NeposGame\Nebuchadnezzar\
  • User data Linux: home/.local/share/NeposGames/Nebuchadnezzar/

Create mod

• Run Nebuchadnezzar and in the console run command mod_create [mod_name]
• This will create mod folder and inside it the mod.lua special def file containing single atom describing your mod.
  • Mod location Windows: Documents\NeposGame\Nebuchadnezzar\
  • Mod location Linux: home/.local/share/NeposGames/Nebuchadnezzar/
• mod.lua properties:
  • title Official name of the mod. Not used in data and referencing but in Mod manager and Steam Workshop
  • description Description of mod. Use \n for line break.
    • May be empty.
  • author Author of the mod.
    • May be empty.
  • homepage Homepage of the mod.
    • May be empty
  • mod_version Version of the mod.
  • game_version Version of the game for which the mod is created.
  • platform_public Should be the mod visible on platform workshop.
    • Currently related only for Steam Worskshop mods.
  • platform_id Mod identificator on platform workshop.
    • Currently related only for Steam Worskshop mods.
    • Auto-generated. Do no change the value.

Enable mod

Mod is now initialized. You should now restart the game after that you should be able to enable your mod in the Mod manager.

Upload mod to workshop

On supported platforms, currently Steam only, you can upload your mod to platform workshop to allow easy download of your mod for the others.

• Mod upload is super easy.
• Simply run command mod_upload [mod_name]
• And wait to upload finish.

Mod update

• If you run the upload for the first time, the game will generate platform mod identificator and writes it in the mod.lua def file.
• If you run the upload next time, game will use this id and update the mod on the platform with the current content.

Mod preview image

Mod can (and should) have preview image.

• Preview image should have size 200px x 200px because it's the size of Steam preview image and also size of Nebuchadnezzar Mod manager preview image.
• To add preview image, just add image named preview.png to the mod root folder.
• Images bigger than 1MB will cause failure of Steam Workshop upload.

Developing mod

When everything is set up, you can start creating mod content.

Error checking

Nebuchadnezzar does not allow to use mod with invalid data, so your mods cannot generate any error to be functional.

• All active mods are loaded during the game initialization.
• All mods are validated during this loading.
• Every detected error is written to log file and console.
• Some errors may be caused by earlier errors, so always check the first error to find the root of the problem.

Base mod(s)

Base mod is Nebuchadnezzar built-in mod containing all Neubchadnezzar data.

• It means you can approach it as any other mod and reference its atoms.
• Its data are located in [game installation folder]/data/mods/base
• Feel free to look up for inspiration.