Getting Started - OperatorJack/Magicka-Expanded GitHub Wiki

This guide describes some basic points of developing a mod using the Magicka Expanded framework. This guide assumes some basic knowledge of Lua, how MWSE-Lua works, and how to develop a mod in MWSE-Lua.

Referencing the Framework

The first step to use the framework is to reference the framework library in your MWSE-Lua script.

At the top of your script, reference the framework library by adding the following code:

local framework = include("OperatorJack.MagickaExpanded.magickaExpanded")

This creates an object reference to the library. MWSE will retrieve the loaded library module and return a copy to the object. This allows you to call functions within the library through the object named framework.

Checking Framework Installation

Referencing the framework does not guarantee the framework is installed. You should always check that the framework is installed before attempting to use it. Below your reference to the framework library, add the following code:

if (framework == nil) then
    local function warning()
        tes3.messageBox(
            "[MY-MOD ERROR] Magicka Expanded framework is not installed!"
            .. " You will need to install it to use this mod."
        )
    end
    event.register("initialized", warning)
    event.register("loaded", warning)
    return
end

This checks that the library object is not nil. If it is not nil, then it is installed and was loaded correctly. If it is nil, then the library was not loaded or is not installed for some reason. If this happens, the return prevents the remainder of the script from running and notifies the user. You should replace MY-MOD with the name of your mod.

Claiming a Spell Effect ID

Next, you must claim a spell effect ID for your spell effect(s). To do this, check for an unclaimed spell effect ID on the spell effect claim Google Spreadsheet. You can go up to ~32,000, so feel free to choose a section of numbers that are far away from any other claimed ID numbers. This is required because Morrowind & MWSE require a key-value table of magic effects where the key of the table is the effect name, and the value is the spell effect ID.

To claim a spell effect ID, add the following code below the framework check:

-- Register the Spell Effect ID.
tes3.claimSpellEffectId("MY-EFFECT-NAME", -1)

Update MY-EFFECT-NAME to your magic effect name, such as lightDamage, and update -1 to the spell effect ID you claimed. Please note that the name used here is not the display name for the effect, but a no-space ID associated with the spell ID number. Other examples: fireDamage, light-damage, lightdamage, etc. light damage is not supported.

Registering a New Spell Effect

Now that you have claimed the spell effect ID for your spell effect, you can register the spell effect in the magic system. Add the following code to your script:

local function onEffectTick()
	-- e.trigger() triggers the spell effect system and is required in the onTick event callback.
	if (not e.trigger()) then
		return
	end

	tes3.MessageBox("My Custom Effect: Tick")
end

local function addMagicEffect()
	-- Here we are creating a basic alteration magic effect.
	framework.effects.alteration.createBasicEffect({
		-- Base information.
		id = tes3.effect.MY-EFFECT-NAME,
		name = "My Magic Effect",
		description = "My cool new magic effect!"
		-- Basic dials.
		baseCost = 0,

       		-- Various flags.
		allowSpellmaking = true,
		allowEnchanting = true,
		appliesOnce = true,
		canCastSelf = true,
		hasNoDuration = true,
		hasNoMagnitude = true,
		nonRecastable = true,

		-- Graphics/sounds.
		icon = "MY_ICONS\\MY_CUSTOM_ICON.dds",

		-- Required callbacks.
		onTick = onEffectTick,
	})
end

event.register("magicEffectsResolved", addMagicEffect)

This code registers a new magic effect in the magic system. On each tick of the spell effect, onEffectTick will be called. Some example configuration options are shown, such as allowing it to be used in enchanting and supplying a custom icon.

Registering a New Spell

After creating the magic effect, registering it to a new or existing spell is easy. Add the following to your code:

local function registerSpells()
    framework.spells.createBasicSpell({
        id = "MY_SPELL",
        name = "My Custom Spell",
        effect = tes3.effect.MY-EFFECT-NAME,
        range = tes3.effectRange.self
    })
end

event.register("MagickaExpanded:Register", registerSpells)

The Magicka Expanded framework provides simple methods to register new basic and complex spells. The code above will create the spell or update the first effect of an existing spell with the same ID.

Distribution of Spells

Once you've registered a spell through the framework, it is now available to be distributed in the same ways as a normal spell, with the caveat that it cannot be done through the Construction Set. Magicka Expanded adds support for "Spell Tomes" to easily distribute large numbers of spells. But, you can use tes3.addSpell or any other option. For example, you could create a spell placeholder in the Construction Set, give it as a reward from a quest in the Dialogue menu in the Construction Set, and as long as you register it as described above, it will still have your custom magic effect!

For more information on any section, please refer to the API.