# 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:

  - name string
  - details table
onSpawnRegionsLoaded (regions)
  Injects custom spawn points into the region table.

  Called automatically by the `OnSpawnRegionsLoaded` event.

  ### Parameters:

  - regions table
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