Scripting Tutorial: My First Spell

My first spell tutorial

This tutorial will help you create a new spell using a combination of predefined and custom effects.

First Steps

If you haven't already, open up the TES Construction Set program. When it's loaded, go to File>Data from the menu bar. Double-click "Oblivion.esm" to load the Oblivion master file.

I lifted this section almost word-for-word from First_Steps. I hear they have a pretty good tutorial over there as well.

Create the Spell

Alright! So, after the arduous loading process, we can start making our spell. Go ahead and locate the Object_Window. We're interested in the Category:Magic category, so expand that option in the list. There are a few items under Magic, but we're creating a spell, so click on the Spell list item.

There should be a whole bunch of spells loaded in the list now. Right-click somewhere in this list (it doesn't matter where) and choose "New" from the context menu that pops up. This brings up a blank Spell dialog.

• ID: The ID is how we refer to the spell inside of the Construction Set. Enter "MyFirstSpell" in this field.
• Name: This is the real name of the spell that is displayed in the game. Enter "My First Spell" in this field.
• Type: What type of spell this is. Leave this as "Spell."

The rest of this dialog is explained on the Spell page.

Currently, my favorite spell name (or more properly, editor ID) is probably DelphineJendEnemiesExplode.

Add Predefined Effects

At this point, the Effects list to the right should be blank. This is a problem as this spell currently doesn't do anything. We'll start by adding a predefined spell effect.

Right-click in the Effects list box and choose "New" from the context menu. This brings up the Effect_Item dialog.

• Effect: This is what magic effect to apply. Let's choose "Shield" from the list
• Range: This is what this spell can affect. Set this to "Self".
• Area: Area of effect. This is disabled for Self spells since they only affect the caster.
• Duration: How long (in seconds) the spell should last. Set this to 30.
• Magnitude: In this case, how much armor to give the caster. Set this to something ridiculous like 300.

Click OK to add this effect.

Did you notice that the values in the Auto-Calculated Costs box to the right are automatically updating? If you don't want these costs to apply to the spell, you can uncheck the Auto-Calculate box on the previous spell screen. Actually, we'll probably be doing this later! How exciting! I love checkboxes.

Create Spell Script

Now that we've added a standard magical effect to our spell, let's add a custom one. In order to add a custom effect, we need to write a script. Select Gameplay->Edit Scripts... from the menubar.

We're now at a blank Edit Scripts window. Select Script->New from the menubar in this window. The textarea will now be enabled.

Choose "Magic Effect" in the Script Type drop down. This is important! If we don't do this, we can't add it to a spell.

Let's name our script "MyFirstSpellScript" and add a variable for later use. Type:

scriptname MyFirstSpellScript

short updateCount

Spell scripts are slightly different from regular scripts. They only recognize 3 script blocks, while other types of scripts can recognize many more. So, what's a script block? I'm glad you asked! Script blocks are blocks of code that are run under certain conditions. Spell scripts recognize these blocks:

• ScriptEffectStart - This block of code is executed when the spell is first cast
• ScriptEffectUpdate - This block of code is executed (approximately) every game frame for the duration of the spell
• ScriptEffectFinish - This block of code is executed at the end of the spell's duration

More information about blocks can be found at the Begin page.

Spell scripts are executed by the actor or object that is targeted by the spell. So, if the spell is a Self spell, the caster of the spell will run the commands in the script. If the spell is targeted, the target will run the spell. If the spell has an area of effect, then everything affected by the spell will run the script.

Let's add the blocks to the script now:

ScriptEffectStart Block

Begin ScriptEffectStart
  RemoveAllItems
End

This effect is pretty fun to use.

ScriptEffectUpdate Block

Begin ScriptEffectUpdate
  set updateCount to updateCount + 1
End

All we're doing in the update block is incrementing a counter. This will tell us how many times it ran. A more interesting use might be to increase or decrease health or something similar.

ScriptEffectFinish Block

Begin ScriptEffectFinish
  Message "Spell is finished. ScriptEffectUpdate was run %.0f times", updateCount
End

This displays a text message to the screen telling us how many times the update block was executed.

Here is the full script:

scriptname MyFirstSpellScript

short updateCount

Begin ScriptEffectStart
  RemoveAllItems
End

Begin ScriptEffectUpdate
  set updateCount to updateCount + 1
End

Begin ScriptEffectFinish
  Message "Spell is finished. ScriptEffectUpdate was run %.0f times", updateCount
End

Choose Script->Save from the menubar (or click on the disk button in the toolbar) and close the Script Edit window.

You can read more about scripting on the Category:Scripting page. Also check out the My_First_Script tutorial.

Add Custom Effects

We should be back at the Spell dialog box. Right-click in the Effects list and choose "New" from the context menu like we did before.

This time, choose "Script Effect" from the Effect drop down box. This lets us use the script that we just wrote.

• Effect: Set this to "Script Effect"
• Range: Set this to "Target" this time.
• Area: Set this to something like 100
• Duration: use a small value like 5 or 10 so we don't have to wait a long time for the script to finish.
• Script Effect Info
  • Script: This is the script to use. Choose "MyFirstSpellScript" from this list. (Note that you can click on the "..." to bring up the script editor window from this screen as well)
  • Effect Name: Name of the effect. Choose something like "I see London, I see France"
  • School: What school this effect belongs to. We don't really care in this case.
  • Visual Effect: What visual effect to use. Choose "Frenzy" from the list.
  • Effect is Hostile: Check this and people won't like it if you cast this spell. (Let's leave this unchecked for now)

Final Touches

Be sure to uncheck "Auto-Calculate" in the spell dialog, or you probably won't be able to cast the spell.

Click "OK" in the spell dialog. The spell should now be added to the spell list in the Object Window.

Find the Form ID

Before we can test this spell, we need to know how to reference it from within the game. Unfortunately we can't just use "MyFirstSpell" so we need to find out what the spell's FormID is.

Go to the top of the spell list and find the "Count" column. Directly to the left of this column, you should see a double column line instead of the usual single line. Click and drag the right line of these double lines to the right to expand the "Form ID" column. Now, scroll down and find the spell we just added. Write down the number in the Form Id column. It should look something like "01000CE8". (but may not be exactly that)

Save

This is important!

Choose File->Save from the menubar. If you were editing a new plugin, you will be prompted for a filename. Choose something memorable like "01000CE8". (Or "MyFirstSpell" would work too I guess)

Testing

Finally we're at the last section! This is where we test the new spell. Go ahead and start Oblivion up. When the launcher comes up, click on the "Data Files" button. Make sure that "Oblivion.esm" and the filename you chose earlier are the only entries checked. Click "OK"

Before you actually click "Play" you may want to read the rest of the tutorial so you don't have to alt-tab. Oblivion doesn't really seem to like alt-tabbing very much. You could even write down or print out the next steps. I'll wait. Another option would be to set Oblivion to run in windowed mode by changing the full screen option to 0 in Oblivion.ini

Click "Play"

Start a new game or load up a save file. Keep in mind that our custom effect works best on multiple targets.

Once you are actually playing, bring up the console by hitting the ~ key, and type the following:

player.addspell <formId>

where <formId> is the formId for the spell. (You did write it down, right?)

It should look something like:

player.addspell 01000ce8

If all goes well, a message will appear notifying you that "My First Spell" was added. Choose this spell from your spellbook and cast it!

You should gain armor, and after a few seconds, a notification message will appear informing you how many times the update block was executed.

If it doesn't go well because the game doesn't recognize the formID you should try increasing its second digit (in our example you would have to substitute 01000ce8 with 02000ce8, 03000ce8...) until it works. You probably have more than the master file and your data file loaded, despite the suggestion above.

Have fun making spells!

Custom Spell Scripting Notes

Functions in a magic effect script run on the target by default, so usually there's no need to worry about the target's ID. But if you do need that info, getSelf will get it for you.