Module ProfessionFramework

Simple Framework for adding or modifying Professions and Traits.

All functions and tables can be accessed via the global table named ProfessionFramework. Generally you will only need to make use of the functions ProfessionFramework.addProfession and ProfessionFramework.addTrait

Examples

-- edit a existing profession, changing skill levels and starting equipment
ProfessionFramework.addProfession('carpenter', {
    cost = 4, -- was 2
    xp = {
        [Perks.Woodwork] = 4,
    },
    inventory = {
        ["Base.Hammer"] = 2,
        ["Base.Saw"] = 1,
        ["Base.Woodglue"] = 3,
        ["Base.NailsBox"] = 3,
    },
    square = {
        ["Base.Plank"] = 10,
    },
})


-- add a new trait that randomly wake up the player in a panic
ProfessionFramework.addTrait('Nightmares', {
    name = "UI_trait_nightmares",
    description = "UI_trait_nightmaresdesc",
    exclude = {"Desensitized"},
    cost = -4,
    requiresSleepEnabled = true,
    inventory = {
        -- starting kit to help get back to sleep
        ["Base.PillsBeta"] = 1,
        ["Base.PillsSleepingTablets"] = 1,
    },
    OnGameStart = function(trait)
        -- add a new event to trigger every ten minutes
        Events.EveryTenMinutes.Add(function()
            local p = getSpecificPlayer(0)
            if p:isAsleep() and ZombRand(100) < 2 then
                p:forceAwake()
                p:getStats():setPanic(90)
            end
        end)
    end
})

Info:

  • Copyright: 2018
  • Release: 1.2
  • Author: Fenris_Wolf

Constants

VERSION Current version number
AUTHOR Author/Maintainer
COMPATIBILITY_MODE Backwards compatibility mode (build 40)

Logging Constants

ERROR integer 0
WARN integer 1
INFO integer 2
DEBUG integer 3

Data Tables

Professions Table of registered professions
Traits Table of registered traits

Configuration Options

RemoveDefaultProfessions Remove all vanilla professions (bool)
RemoveDefaultTraits Remove all vanilla traits (bool) note this flag should not normally be used, as several traits overweight/underweight/etc are essentially required by the game.
AlwaysUseStartingKits Always supply starting kits, false to obey sandbox settings (bool)
LogLevel Logging level verbosity.
ExperimentalFeatures Experimental Features.

Functions

log (level, text) Basic logging function.
addProfession (type, details) Registers a profession with the profession framework.
getProfession (type) Returns the details of a registered profession.
addTrait (type, details) Registers a trait with the profession framework.
getTrait (type) Returns the details of a registered trait.

Automatically Called Functions

doTraits () Adds all registered traits to the java TraitFactory.
doProfessions () Adds all registered professions to the java ProfessionFactory.
addStartingKit (player, square, details) Adds starting kits for any profession and traits.
getRestrictedTraits (profession, current_traits) Returns a table list of traits that should be restricted.
addClothes (name, details) Adds clothes to the character creation screen.
onSpawnRegionsLoaded (regions) Injects custom spawn points into the region table.
onGameStart () Triggered when the player enters the game world.
onNewGame (player, square) Triggered when the player enters the game world for the first time.


Constants

VERSION
Current version number
AUTHOR
Author/Maintainer
COMPATIBILITY_MODE
Backwards compatibility mode (build 40)

Logging Constants

These are passed to and checked when making calls to ProfessionFramework.log.
ERROR
integer 0
WARN
integer 1
INFO
integer 2
DEBUG
integer 3

Data Tables

These should not be directly accessed, use function such as ProfessionFramework.addProfession and ProfessionFramework.getProfession instead
Professions
Table of registered professions
Traits
Table of registered traits

Configuration Options

RemoveDefaultProfessions
Remove all vanilla professions (bool)
RemoveDefaultTraits
Remove all vanilla traits (bool) note this flag should not normally be used, as several traits overweight/underweight/etc are essentially required by the game. however required traits can be recreated using the PF if needed.
AlwaysUseStartingKits
Always supply starting kits, false to obey sandbox settings (bool)
LogLevel
Logging level verbosity.
ExperimentalFeatures
Experimental Features. Enable at own risk. Expect breakage.

Functions

log (level, text)
Basic logging function.

Prints a message to the console and console.txt log, if ProfessionFramework.LogLevel is equal or less then the level arguement.

Parameters:

  • level int logging level constant
  • text string text message to log.

Usage:

    ProfessionFramework.log(ProfessionFramework.WARN, "this is a warning log message")
addProfession (type, details)
Registers a profession with the profession framework.

Defines a profession selectable by the player. Both new custom professions and the default vanilla ones can be defined in this manor.

When overwriting a vanilla (or pre-existing) profession, not all key/value pairs in the details table argument will be valid as the existing entries will be modified. Vanilla professions do not need to be registered with this function, but won’t be able to make use of the ProfessionFramework’s features unless they are.

Note no action is taken when this function is called, other then inserting into the ProfessionFramework.Professions table. Any calls to this function need to be done before the OnGameBoot event.

Parameters:

  • type string name of the profession
  • details table a table containing the profession details.

Returns:

    table the details table passed as a arg

    Valid key/value pairs the details table are:

    • name = string value of a translation key. (default “Unknown”)

    • cost = integer value, the number of points this profession starts with. (default 0)

    • icon = string value, image filename (without extension) to use. (default “”)

    • xp = a table of perk enum values (keys), and the experience levels for each (values). (default nil)

    • traits = a table list of traits this profession starts with. (default nil)

    • recipes = a table list of recipes this profession starts with. (default nil)

    • inventory = a table of items the profession starts with. Keys are item names, values are the count. (default nil)

    • square = a table of items the profession starts with (on the ground). Keys are item names, values are the count. (default nil)

    • spawns = a table of region names (keys), and subtable values of spawn locations. Use of this key will overrides vanilla regions. (default nil)

    • clothing = a table of BodyLocations and subtable values of clothing items to enable on the character creation screen. (default nil)
      The clothing table supports several ‘special’ key/value pairs:

      • replace bool value, completely replaces all vanilla clothing options (default false)

      • replace_items bool value, only replace vanilla options for the BodyLocations specified in this table. (default false)

      • Male clothing subtable for male selection only (default nil)

      • Female clothing subtable for female seleciton only (default nil)

    • OnNewGame = a function to be called when the character is created. (default nil)
      Arguments are a IsoPlayer object, a IsoGridSquare object, and the string profession name.

    Note unlike the details table passed to ProfessionFramework.addTrait, the profession table does not include a description key. The description’s translation string is automatically generated by PZ, using a UI_profdesc_ prefix such as UI_prof_unemployed

getProfession (type)
Returns the details of a registered profession.

Parameters:

  • type string The name of the profession

Returns:

    nil or table the profession details or nil
addTrait (type, details)
Registers a trait with the profession framework.

Defines a trait selectable by the player. Both new custom traits and the default vanilla ones can be defined in this manor.

When overwriting a vanilla (or pre-existing) trait, not all key/value pairs in the details table argument will be valid as the existing entries will be modified. Vanilla traits do not need to be registered with this function, but won’t be able to make use of the ProfessionFramework’s features unless they are.

Note no action is taken when this function is called, other then inserting into the ProfessionFramework.Traits table. Any calls to this function need to be done before the OnGameBoot event.

Parameters:

  • type string name of the trait
  • details table

    a table containing the profession details.

    Valid key/value pairs the details table are:

    • cost: (integer) the number of points this trait costs.
      Note: Can not be adjusted for traits already registered with the java TraitFactory.

    • name: (string) name of the trait (or of the translation entry).
      Note: Can not be adjusted for traits already registered with the java TraitFactory.

    • description: (string) description of the trait (or of the translation entry).
      Note: Can not be adjusted for traits already registered with the java TraitFactory.

    • removeInMP: (bool) Is this trait only for single player mode
      Note: Can not be adjusted for traits already registered with the java TraitFactory.

    • requiresSleepEnabled: (bool) Sleeping must be enabled in sandbox settings to select. (MP only)
      Note: Can not be adjusted for traits already registered with the java TraitFactory.

    • profession: (bool) Is this trait a ‘profession trait’ (non-selectable)
      Note: Can not be adjusted for traits already registered with the java TraitFactory.

    • xp: (table) perk enum values (keys), and the experience levels for each (values).
      Note when using the xp table on a trait already setup with the java TraitFactory this table will not change existing xp levels unless they are redefined here.

    • swap: (string) name of another trait to swap this one with OnNewGame. This trait is removed from the player, and the new one added This should only really be used for the ‘special’ traits.

    • exclude: (table) list of traits this one should be mutually exclusive with.

    • add: (table) list of additional traits to add to the player OnNewGame

    • inventory: (table) containing items this trait starts with. Keys are item names, values are the count.

    • square: (table) containing items this trait starts with (on the ground). Keys the item names, values are the count.

    • OnNewGame: (function) a callback executed when the character is created if it has this trait. Arguments are:
      a IsoPlayer object, a IsoGridSquare object, and the string trait name.

    • OnGameStart: (function) a callback executed OnGameStart if the player has this trait. Arguments are:
      the string trait name.

getTrait (type)
Returns the details of a registered trait.

Parameters:

  • type string The name of the trait

Returns:

    nil or table The trait details or nil

Automatically Called Functions

doTraits ()
Adds all registered traits to the java TraitFactory.

This function is called automatically with the OnGameBoot event, and overrides the vanilla BaseGameCharacterDetails.DoTraits

It calls the original BaseGameCharacterDetails.DoTraits before running its custom code unless RemoveDefaultTraits is true.

The overwrite is required to ensure custom traits are still available in MP after player death.

doProfessions ()
Adds all registered professions to the java ProfessionFactory.

This function is called automatically with the OnGameBoot event, and overrides the vanilla BaseGameCharacterDetails.DoProfessions

It calls the original BaseGameCharacterDetails.DoProfessions before running its custom code unless ProfessionFramework.RemoveDefaultProfessions is true. The overwrite is required to ensure custom traits are still available in MP after player death.

addStartingKit (player, square, details)
Adds starting kits for any profession and traits.

This function is called automatically by ProfessionFramework.onNewGame

Parameters:

  • player IsoPlayer
  • square IsoGridSquare
  • details table
getRestrictedTraits (profession, current_traits)
Returns a table list of traits that should be restricted.

Note this currently experimental, and requires ProfessionFramework.ExperimentalFeatures

Parameters:

  • profession string the string name of the profession to check against.
  • current_traits table a table list of traits already selected.

Returns:

    table a table list of traits this character shouldn’t have.
addClothes (name, details)
Adds clothes to the character creation screen.

Called automatically by ProfessionFramework.doProfessions

Parameters:

onSpawnRegionsLoaded (regions)
Injects custom spawn points into the region table.

Called automatically by the OnSpawnRegionsLoaded event.

Parameters:

onGameStart ()
Triggered when the player enters the game world.

Called automatically by the OnGameStart event hooked in ProfessionFrameworkClient.

Runs any custom trait OnGameStart callbacks for the player’s traits.

onNewGame (player, square)
Triggered when the player enters the game world for the first time.

Called automatically by the OnNewGame event hooked in ProfessionFrameworkClient.

Runs any custom OnNewGame callbacks and calls ProfessionFramework.addStartingKit for the player’s chosen traits and profession. Any traits defined with the swap key will be swapped out here.

Parameters:

  • player IsoPlayer
  • square IsoGridSquare
generated by LDoc 1.4.6 Last updated 2022-01-10 09:07:12