4.03. Scripting API

API DOCUMENTATION

Important

To reduce the chances that your script will break use interfaces instead of classes (e.g. Use IChampion, ISpell, IAttackableUnit etc).

Each script's class name (e.g. public class EzrealMysticShot) must correspond to a data file present in the Content folder.

You can find all of the base spells a character uses in GameServer/Content/LeagueSandbox-Default/Stats/CharacterName.json.
Click here for an example of Ezreal's data file.
As you can see from the link, each QWER spell is located in that file, as well as additional spells such as EzrealMysticShotMissile, which are usually denoted ExtraSpell in character data files. The number next to it ExtraSpell1/2/3 denotes the spell slot (but you'll need to subtract 1 to use with the SpellCast function).

Spell Template / Creating a Spell

The spells are programmed in C#. They are in GameServer/Content/LeagueSandbox-Scripts/Champions/ChampionName. In each champion's folder there should be a Passive.cs, Q.cs, W.cs, E.cs and R.cs.

A spell should have a template by default like this (if not, delete all and paste this template):

using System.Collections.Generic;
using System.Numerics;
using GameServerCore.Domain.GameObjects;
using GameServerCore.Domain.GameObjects.Spell;
using GameServerCore.Domain.GameObjects.Spell.Missile;
using GameServerCore.Enums;
using LeagueSandbox.GameServer.API;
using static LeagueSandbox.GameServer.API.ApiFunctionManager;
using LeagueSandbox.GameServer.Scripting.CSharp;

namespace Spells
{
    public class SPELL_NAME : ISpellScript
    {
        public ISpellScriptMetadata ScriptMetadata { get; private set; } = new SpellScriptMetadata()
        {
        };

        public void OnActivate(IObjAiBase owner, ISpell spell)
        {
        }

        public void OnDeactivate(IObjAiBase owner, ISpell spell)
        {
        }

        public void OnSpellPreCast(IObjAiBase owner, ISpell spell, IAttackableUnit target, Vector2 start, Vector2 end)
        {
        }

        public void OnSpellCast(ISpell spell)
        {
        }

        public void OnSpellPostCast(ISpell spell)
        {
        }

        public void OnSpellChannel(ISpell spell)
        {
        }

        public void OnSpellChannelCancel(ISpell spell)
        {
        }

        public void OnSpellPostChannel(ISpell spell)
        {
        }

        public void OnUpdate(float diff)
        {
        }
    }

    public class SPELL_MISSILE_NAME : ISpellScript
    {
        public ISpellScriptMetadata ScriptMetadata { get; private set; } = new SpellScriptMetadata()
        {
        };

        public void OnActivate(IObjAiBase owner, ISpell spell)
        {
        }

        public void OnDeactivate(IObjAiBase owner, ISpell spell)
        {
        }

        public void OnSpellPreCast(IObjAiBase owner, ISpell spell, IAttackableUnit target, Vector2 start, Vector2 end)
        {
        }

        public void OnSpellCast(ISpell spell)
        {
        }

        public void OnSpellPostCast(ISpell spell)
        {
        }

        public void OnSpellChannel(ISpell spell)
        {
        }

        public void OnSpellChannelCancel(ISpell spell)
        {
        }

        public void OnSpellPostChannel(ISpell spell)
        {
        }

        public void OnUpdate(float diff)
        {
        }
    }
}

OnSpellPreCast

Read as soon as you click the spell/ability and before the spell has started casting.
owner is your champion.
spell is the spell you cast, has information like CastInfo, which includes SpellLevel.
target is the unit you casted the spell on, if casted on the ground, this will be null.
start and end are the coordinates of your mouse when you clicked the ability.

ScriptMetadata

Contains parameters which control the behavior of the spell script.
The parameter TriggersSpellCasts enables OnSpellCast and OnSpellPostCast.
The parameter CastTime allows you to override the cast time of the ability.
The parameter CastingBreaksStealth is self-explanatory.
The parameter ChannelDuration will enable the spell channel functions.
Currently the rest of the parameters are un-implemented so they can be ignored.

MissileParameters

Contains parameters for controlling the behavior of a missile spell.
Missile spells often require separate scripts. As shown in the example, they can be within the same C# file.
If the missile spell's internal name is the same as the spell that casts it, like Disintegrate for Annie Q, then you may have MissileParameters defined in the main script, and it will automatically create the missile.
Otherwise, create a separate class with the missile spell's name, and have MissileParameters in the new class. To create the missile from the main spell script, you will need to use the SpellCast API function when needed.

SectorParameters

Contains parameters for controlling the behavior of a spell sector, which are area of effect spells.

OnUpdate

Read about 60 times a second.
diff is the time in milliseconds past since last frame.

Assuming you have TriggersSpellCasts = true, the rest of the spell cast functions will be enabled, and the following will apply:

OnSpellCast

Read when the player starts casting the ability (all CastInfo initialized).
It only has the parameter spell, however it's CastInfo variable contains all information required, such as CastInfo.Owner, CastInfo.Targets[0].Unit, or positional target like CastInfo.TargetPosition/End.

OnSpellPostCast

Read when the player finishes casting the ability.
It has the same spell parameter as OnSpellCast.

Assuming you have a ChannelDuration which is greater than 0, then the spell channel functions will be enabled and the following will apply:

The rest of the functions like OnSpellChannel and OnSpellPostChannel function the same as the cast functions, just for channels.

OnSpellChannelCancel

Called whenever the channel of the spell stops abruptly mid-channel and does not function after channeling has finished. If the stop source for the abrupt cancel is TimeCompleted, then it will automatically trigger OnSpellPostChannel.

Helper Functions

SpellCast

As mentioned in the MissileParameters section, if the spell is separate from the missile spell, then you will need to use this` function, which manually casts a spell from the list of spells in the character's content file.
If the parameter overrideCastPosition is not a Vector2.Zero, then the missile launched from the spell will start at that position.
- Otherwise, it will start at the spell owner's position.
The spell missile will start from the cast position and move towards the endPos (or pos if endPos is Vector2.Zero).

GetPointFromUnit

This is used to get a point some distance in front of a unit. You'll mostly use this for skill shots to get their end position.
This supports an angle offset in the clockwise direction from where the unit is facing. This will often be used for multi-missile spells like Ashe W.

ForceMovement

This function makes a unit perform a dash.

FaceDirection

This is useful for when you need to make sure GetPointFromUnit is properly aimed in the direction of the player's mouse when casting the spell.

SealSpellSlot

This is useful for if you would like to prevent the player from casting a particular spell.

SetAnimStates

This is useful for champions that transform without changing their model, like Aatrox after casting R.

PlayAnimation

This is useful for when the spell does not automatically play an animation when casting, or if there are special animations not tailored to the initial cast.

Events

The API contains events which you can use like OnSpellHit, OnLaunchAttack, and OnLaunchMissile. An example usage is as follows: ApiEventManager.OnSpellHit.AddListener(this, new System.Collections.Generic.KeyValuePair<ISpell, IObjAiBase>(spell, owner), TargetExecute, false);

The parameters in order are this, which is the object, or class, that hooked onto the event.
new System.Collections.Generic.KeyValuePair<ISpell, IObjAiBase>(spell, owner) is the condition for when the event should be called. spell is the spell that hit, and owner is the unit that cast the spell that hit.
TargetExecute is the name of the function to call when this event triggers. The function must have the parameters (ISpell, IAttackableUnit, ISpellMissile) to be accepted.
- Hovering over the AddListener part will show the parameters required for the function to be called. Each event may have different parameters it supports for the function callback, so be sure to check, otherwise you'll get an error.