Skip to content

Interoperability

Jump to bottom
Merlord edited this page Oct 29, 2023 · 54 revisions

Ashfall has a number of APIs that allow you to easily add compatibility with your mod. If your mod adds new items, regions, or heat sources, you can register their ids in a simple script that sits in the Data Files/MWSE/mods/[modName] folder. This script only does something if MWSE and Ashfall are installed, otherwise it is safely ignored.

It is recommended you set Ashfall's log level to DEBUG in the MCM (under Development Options->Log Level) while creating your API functions. Check mwse.log to see if your functions were successful.

To begin, start with Creating an Interop File.

APIs

Quick Reference:

--Data Files/MWSE/mods/[ModName]/main.lua
local ashfall = include("mer.ashfall.interop")
if ashfall then

    --Object Registration

    ashfall.registerActivatorType({
        id = "myCustomActivator",
        name = "My Custom Activator",
        type = "myCustomActivator",
        ids = {
            "my_activator_id_01",
            "my_activator_id_02",
        }
    })

    ashfall.registerActivators{
        ex_water_01 = "water",
        in_fountain_01 = "waterClean",
        mymod_well_01 = "well",
        id_ex_tree_01 = "tree",
        ex_log_01 = "wood",
    }

    ashfall.registerWaterSource{
        name = "Dirty Well",
        isDirty = true,
        ids = {
            "dirty_well_01",
            "dirty_well_01"
        }
    }

    ashfall.registerWaterContainers{
        misc_cup_01 = "cup",
        mymod_misc_bottle_01 = "bottle",
        t_misc_jug_01 = "jug",
        t_misc_flask_01 = "flask",
        misc_pitcher_01 = "pitcher",
        misc_pot_01 = "pot",
    }

    ashfall.registerFoods{
        a_ingred_pork_01 = "meat",
        a_ingred_pork_cooked_01 = "cookedMeat"
        ingred_mushroom_01 = "mushroom",
        mymod_ingred_vegetable_01 = "vegetable",
        mymod_ingred_egg_01 = "egg",
        mymod_ingred_herb_01 = "herb",
        mymod_ingred_salt_01 = "seasoning",
        mymod_ingred_big_mac_01 = "food",
    }

    ashfall.registerHeatSources{
        mymod_ex_flame_01 = 100,
        mymod_ex_lavapool_01 = 250,
        id_ice_cube_01 = -50
    }

    ashfall.registerClimates{
        ["The Hot Lands"] = 'volcanic',
        ["Frigid Wastes"] = 'polar'
        ["My Custom Region"] = { min = -50, max = 50 },
    }

   ashfall.registerTreeBranches{
        treeIds = {
            'flora_custom_tree_01',
            'flora_custom_tree_02',
        },
        branchIds = {
            "custom_branch_01",
            "custom_branch_02",
            "custom_branch_03",
        }
    } 

    ashfall.registerWoodAxes{
        "ebony war axe"
    }



    --Skills

    local skillLevel = ashfall.getSurvivalSkill()

    ashfall.progressSurvivalSkill(20)


    --Overrides
    ashfall.registerOverrides{
        ingred_crab_meat_01 = {
            weight = 0.5,
            value = 15,
        },
        ingred_hound_meat_01 = {
            weight = 2,
            value = 20,
        }
    }
end

Creating an Interop File

Create a folder named after your mod in Data Files/MWSE/mods, then inside that, create a file called main.lua. So if our mod name was called "Test Mod", it might look something like this:

Data Files/MWSE/mods/TestMod/main.lua

Open main.lua with an IDE or text editor, such as notepad++. Add the following text:

local ashfall = include("mer.ashfall.interop")
if ashfall then


end

In the space between if ashfall then and end is where you put the functions that call the Ashfall APIs. For example:

local ashfall = include("mer.ashfall.interop")
if ashfall then

    ashfall.registerActivators{
        mymod_water_01 = "water",
        mymod_ex_log_01 = "wood"
    }

end

Condition APIs

These APIs expose the various condition values of the player, such as hunger and tiredness.

Function Description
getHunger Returns the player's current hunger value, ranging from 0 (satiated) to 100 (starving)
setHunger Set the player's hunger to the passed value, e.g. setHunger(50)
getThirst Returns the player's current thirst value, ranging from 0 (hydrated) to 100 (dehydrated)
setThirst Set the player's thirst to the passed value, e.g. setThirst(50)
getTiredness Returns the player's current tiredness value, ranging from 0 (well rested) to 100 (exhausted)
setTiredness Set the player's tiredness to the passed value, e.g. setTiredness(50)
getTemp Returns the player's current temperature value, ranging from -100 (freezing) to 100 (scorching)
setTemp Set the player's temperature to the passed value, e.g. setTemp(50)
getWetness Returns the player's current hunger value, ranging from 0 (dry) to 100 (soaked)
setWetness Set the player's wetness to the passed value, e.g. setWetness(50)

Object Registration APIs

Use the following APIs to add Ashfall compatibility to your modded objects.

Register Activator Type

Use this API to register a custom activator that isn't part of Ashfall itself.

Pass the function a table with the following values:

  • id: string. Make it unique, a prefix named after your mod is recommended to avoid conflicts.
  • name: string. Determines what is shown in the tooltip when looking at the activator.
  • type: string. Can be an existing type (See the Register Activators section below, or a unique one. If making a unique one, I suggest making it the same as the activator id.
  • ids: (optional) table of strings. A list of object ids that will be registered as this activator type
  • patterns: (optional) table of strings. A list of patterns matched against object ids. This has a performance impact so it is recommended you use full ids instead of patterns.

Usage

    ashfall.registerActivatorType({
        id = "myCustomActivator",
        name = "My Custom Activator",
        type = "myCustomActivator",
        ids = {
            "my_activator_id_01",
            "my_activator_id_02",
        },
        patterns = {
            "mymod_",
        }
    })

Register Activators

Use this API to register new sources of firewood and water.

Pass the function a table of key/value pairs. Keys must be ids of activator or static objects. Values must be strings matching the Activator Types listed below.

Activator Types

Activator Type Description Tooltip
waterClean Provides clean water when activated. Water
waterDirty Bodies of water such as lakes and streams. Provides dirty water when activated. Water (Dirty)
water Alias of waterDirty Water (Dirty)
well Provides clean water when activated. Well
basin Provides clean water when activated. Basin
tree Harvest wood and resin by chopping with an axe. Tree
wood Harvest wood by chopping with an axe. Wood
stoneSource Harvest stone by using a pickaxe. Rock

Usage

ashfall.registerActivators{
    mymod_water_01 = "water",
    mymod_water_clean_01 = "waterClean",
    mymod_ex_log_01 = "wood"
}

Register Water Source

Use this API to register a water source with a unique name. Only use this if your water source has a unique name that is not covered by the Activator Types listed here, otherwise use the registerActivators interop instead.

Pass a name for the water source, an optional isDirty flag, and a list of ids of activator or static objects which will be registered as water sources.

Usage

ashfall.registerWaterSource{
    name = "Dirty Well",
    isDirty = true,
    ids = {
        "dirty_well_01",
        "dirty_well_02"
    }
}

Register Water Containers

Use this API to register containers to hold water/tea/stew.

Pass the function a table of key/value pairs. Keys must be ids of misc objects. Values must be strings matching the Water Container Types listed below.

Water Container Types

Water Container Type Capacity Holds Stew
cup 20 false
glass 20 false
goblet 20 false
mug 30 false
tankard 30 false
flask 80 false
bottle 90 false
pot 100 true
jug 200 false
pitcher 19 false

Usage

ashfall.registerWaterContainers{
    myMod_misc_bottle_01 = "bottle",
    myMod_misc_jug_01 = "jug",
}

Register Foods

Use this API to register new foods.

Pass the function a table of key/value pairs. Keys must be lowercase ids of alchemy or ingredient objects. Values must be strings matching the Food Types listed below.

Food Types

Food Type Description
food Pre-made food such as bread and scuttle.
meat Must be cooked in a grill or a stew before it is safe to eat.
cookedMeat Pre-cooked meat, as if it had been cooked on a grill.
egg Provides moderate amount of nutrition.
vegetable Can be eaten raw for a medium amount of nutrition, or grilled to improve nutrition value even further.
mushroom Can be grilled to increase nutrition.
herb Provides little nutrition, used in stews.
seasoning Provides next to no nutrition, used in stews.

See the Cooking page for more info on the different food types.

Usage

ashfall.registerFoods{
    mymod_ingred_mushroom_01 = "mushroom",
    mymod_ingred_meat_cooked_01 = "cookedMeat"
}

Register Wood Axes

Use this to register an axe as a "wood axe", which will cause it to chop wood faster and lose condition slower.

Pass the function a table of axe ids.

Usage

ashfall.registerWoodAxes{
    "ebony war axe",
    "steel axe"
}

Register Heat Sources

Use this API to register new heat sources. You can also register "cold" sources by providing a negative value.

Pass the function a table of key/value pairs. Keys must be ids of objects. Values must be numbers ranging from 0 to 500, indicating the heat emitted by the object.

Example Heat Values

Source Heat Value
Fire 100
Steam Vent 80
Lava Pool 250

Usage

ashfall.registerHeatSources{
    myMod_ex_flame_01 = 100,
    myMod_ex_lavapool_01 = 250,
    id_ice_cube_01 = -50
}

Register Region Climates

Use this API to register climates for new regions. Min and max values correspond to the temperature at midnight and midday, respectively.

Pass the function a table of key/value pairs. Keys must be ids of regions. Values must either be a table with min and max temperature values, or a string matching the following climate types:

Climate Types

Climate Type Min Temp Max Temp
polar -80 -50
cold -65 -40
mild -40 -20
temperate -30 -10
tropical -20 5
dry -35 10
volcanic 0 15

Usage

ashfall.registerClimates{
    ["The Hot Lands"] = 'volcanic',
    ["Frigid Wastes"] = 'polar'
    ["My Custom Region"] = { min = -50, max = 50 },
}

Register Tree Branches

Use this API to register trees to drop specific branch objects. Provide a list of tree object ids and a list of branch ids. Each tree in the list will only drop branches chosen at random from the list of branches provided. To make each tree drop a different kind of branch, call this API once per tree type.

Usage

   ashfall.registerTreeBranches{
        treeIds = {
            'flora_custom_tree_01',
            'flora_custom_tree_02',
        },
        branchIds = {
            "custom_branch_01",
            "custom_branch_02",
            "custom_branch_03",
        }
    }

Skill APIs

Use these to interact with the Ashfall Survival Skill.

Get Survival Skill

Returns the player's current Survival skill level

ashfall.getSurvivalSkill()

Progress Survival Skill

Progresses the player's Survival skill, causing a level up if progress reaches 100.

ashfall.progressSurvivalSkill(50)

Example

In this example, we have some action whose chance of success depends on the Survival skill, and when performed successfully, progresses the skill by 10 points:

local ashfall = include("mer.ashfall.interop")
if ashfall then
    --calculate chance of success
    local survivalSkill = ashfall.getSurvivalSkill()
    local minChance, maxChance = 0.25, 1.0
    local successChance = math.remap(survivalSkill, 0, 100, minChance, maxChance)
    if math.rand() < successChance then
        performAction()
        ashfall.progressSurvivalSkill(10)
    end
end

Overrides

Override the weight and/or value of an item. Useful for balancing values of items that have additional functionality in Ashfall, such as food and water containers.

Example

    ashfall.registerOverrides{
        ingred_crab_meat_01 = {
            weight = 0.5,
            value = 15,
        },
        ingred_hound_meat_01 = {
            weight = 2,
            value = 20,
        }
    }

ko-fi

Clone this wiki locally
  翻译：