Coding Item-Based Battle Sequences
by Gryphon
How to construct an item-based battle sequence
ARTICLE PREREQUISITES: Before reading this article, you should already be very comfortable with the CYS editor and scripting techniques. You should know how to use $PAGETEXT and $DEST commands, and item and link scripts.
Constructing battle sequences can often the the toughest and most time-consuming part of coding an RPG. Yet it’s very important for the player’s experience of the game; boring battle sequences or battles where the player’s weapons and abilities don’t seem to have much impact can easily make them bored with the game as a whole. However, coding narrative and flexible battle systems can quickly balloon into a massive and time-consuming undertaking.
This system is designed to hit a balance between complexity and player flexibility, allowing the player to use any of their weapons and abilities freely during combat, but not taking a ludicrously long amount of time to code.
This guide will first walk you through the creation of a simplistic form of this structure, and then list a number of customization options. It’s recommended that you read the whole article before you start coding, as if you choose to use some of the customization options they will need to be included from the start.
STEP ONE: Create variables.
Create the following variables:
%ATTACK: A storage variable that keeps track of the player’s attack score round-to-round.
%DODGE: A storage variable that keeps track of the player’s dodge score round-to-round
%MODWEAPON: This value keeps track of how powerful the player's weapon is.
%HEALTH: This keeps track of the player’s health. It should start at a value of 10.
%MOBLIFE01: This keeps track of the monster’s health. It should start at a value of 7.
%BATTLE: This keeps the game in “combat mode,” ensuring that you don’t have to code a new item effect for each individual page.
STEP TWO: Create & code items.
Create two items: “Sword” and “Great sword.”
Paste the following code into the “Sword” item script:
%MODWEAPON := 1
%ATTACK := 1D10 + %MODWEAPON
%DODGE := 1D10 + %MODWEAPON
IF %BATTLE = 1 THEN $DEST := @P(melee attack)
Paste the following code into the “Great sword” item script:
%MODWEAPON := 2
%ATTACK := 1D10 + %MODWEAPON
%DODGE := 1D10 + %MODWEAPON
IF %BATTLE = 1 THEN $DEST := @P(melee attack)
The code surrounding the “attack” and “dodge” variables will play every time the player uses the weapon, determining whether or not they take and deal damage. The %MODWEAPON keeps track of how powerful that attack is.
The “@P(melee attack)” will have to be selected by you, depending on what page of your story this takes place.
The %BATTLE variable ensure that while the player is in this battle sequence they will be sent to the right page. Each new battle sequence you code should have its own %BATTLE value, which you will code into each item script to send the player to the right page.
STEP THREE: Code page script.
Create a page called “melee attack” and paste the following code in the page script:
IF %ATTACK > 4 THEN %MOBLIFE01 := %MOBLIFE - 1
IF %ATTACK > 5 THEN %MOBLIFE01 := %MOBLIFE - 1
IF %ATTACK > 6 THEN %MOBLIFE01 := %MOBLIFE - 1
IF %DODGE < 5 THEN %HEALTH := %HEALTH - 1
IF %DODGE < 6 THEN %HEALTH := %HEALTH - 1
IF %DODGE < 7 THEN %HEALTH := %HEALTH - 1
This is set up so that the player and monster each can deal 0-3 points of damage on a single round, with a “roll” of 5 or higher dealing damage. You can change the values depending on how powerful you want each individual monster to be.
On every page you create, you may want to include the following lines of code in the page script:
$PAGETEXT := $PAGETEXT + “Player health: “ + %HEALTH
$PAGETEXT := $PAGETEXT + “Monster health: “ + %MOBLIFE01
This will make the player’s health and monster’s health appear at the bottom of each page.
STEP FOUR: Write flavor text.
Create a page called “Melee attack”. Paste the following onto the page:
“You slash your sword at the monster, %%ATTACK%>%4%striking it in the side and drawing blood.%%%%ATTACK%<%5%but it dodges your strike.%%
The monster swipes at you with its claws, %%DODGE%<%5%and you wince in pain as it slashes your side.%%%%DODGE%>%4%but you leap away in time.%%”
This way, the appropriate flavor text will show when you or the monster is dealt damage.
STEP FIVE: Code the end of the battle.
Code the %HEALTH variable so that if it drops below 1 it takes the player to a page titled “Game over” with an endgame link.
Code the %MOBLIFE01 variable so that if it drops below 1 it takes the player to a page titled “Monster defeated”. In the page script to this page, have the code %BATTLE := 0 to take the game out of combat mode. Then, you can write a short blurb of flavor text describing the monster’s defeat and what happens next.
At this point, you’ve coded the battle. The player can attack with either the sword or great sword, switching freely at any time.
This is obviously an extremely simplistic system with only two near-identical weapons and no options other than simply attacking. The customization options below explain how to add stat-based effects, multiple weapon types, different attack types, ranged weapons, armor, and more to this system.
Customization options:
Note: This article assumes in places that you begin using earlier customization options, and references them in later ones. If you want to use a later customization option but not an earlier one, just ignore the parts of the text and code that refer to the previous one. If you are copy-pasting the code, you may need to delete some parts.
1) Stat-based combat.
If you’re using statistics such as “strength” and “agility,” you can easily add them to this system.
STEP ONE: Create variables.
%STRENGTH and %AGILITY are generally used, but it can be whatever fits with your game system.
STEP TWO: Adjust item scripts.
You’ll need to change the code that calculates %ATTACK and %DODGE on each item you’ve created to the following:
%ATTACK := 1D10 + %MODWEAPON + %STRENGTH
%DODGE := 1D10 + %AGILITY
Now whether or not the player and monster takes damage is affected by the player’s statistics. You’ll need to adjust the value of the player’s statistics in order to make sure the game is balanced; having them between -2 and 2 should work well with the numbers used in this article.
2) Multiple weapon types
Obviously a combat sequence that only lets the player use various sword types isn’t very useful.
STEP ONE: Create variables.
Create the following variables:
%WEAPONUSED: This will keep track of which weapon the player is using.
STEP TWO: Create & code items.
Obviously you can adjust the weapon types and values to fit your game.
Add the following line of code to the “Sword” item:
%WEAPONUSED := 1
Add the following line of code to the “Great sword” item:
%WEAPONUSED := 2
Create an item titled “Axe” with the following item script:
%MODWEAPON := 2
%WEAPONUSED := 3
%ATTACK := 1D10 + %MODWEAPON
%DODGE := 1D10
IF %BATTLE = 1 THEN $DEST := @P(melee attack)
Create an item titled “Dagger” with the following item script:
%MODWEAPON := 0
%WEAPONUSED := 4
%ATTACK := 1D10 + %MODWEAPON
%DODGE := 1D10
IF %BATTLE = 1 THEN $DEST := @P(melee attack)
Create an item titled “Spear” with the following item script:
%MODWEAPON := 1
%WEAPONUSED := 5
%ATTACK := 1D10 + %MODWEAPON
%DODGE := 1D10
IF %BATTLE = 1 THEN $DEST := @P(melee attack)
Altering the %MODWEAPON variable will make some weapons more powerful than others. The axe is the most powerful here, and the dagger is the least powerful.
If you’re including player statistics, this is another good way to differentiate weapon types, by making some strength-based and some precision-based.
STEP THREE: Edit flavor text.
Change the “Melee attack” page’s text to show the following:
“You slash your %%WEAPONUSED%=%1%sword%%%%WEAPONUSED%=%2%great sword%%%%WEAPONUSED%=%3%axe%%%%WEAPONUSED%=%4%dagger%%%%WEAPONUSED%=%5%spear%% at the monster, %%ATTACK%>%4%striking it in the side and drawing blood.%%%%ATTACK%<%5%but it dodges your strike.%%
The monster swipes at you with its claws, %%DODGE%<%5%and you wince in pain as it slashes your side.%%%%DODGE%>%4%but you leap away in time.%%”
The text will now include flavor text for whichever weapon the player is using.
If you want different weapons to have alternate effects other than just the weapon modifier and flavor text, you'll need to code a new "melee attack" page for that weapon, and change $DEST in that item's script to lead to that page.
3) Multiple attack options
You can give the player the option to attack in multiple different ways, such as attacking with their strength score, or another statistic, such as “precision.” To do so, you will first need to code attack links onto the page, rather than relying on the player continuing combat by using the items.
STEP ONE: Create “slash” link.
Create a link titled “slash” on the “melee attack” page, which leads to the “melee attack” page. Paste the following code in the link script:
%ATTACK := 1D10 + %MODWEAPON + %STRENGTH
%DODGE := 1D10 + %AGILITY
The game remembers which weapon the player has most recently used, and assumes they will continue to use that weapon. Once they switch weapons by using a new weapon, the %MODWEAPON variable will change to reflect it.
The “slash” link is the default attack option, similar to just choosing to use an item. You can now provide the player with other options, however. Here are some suggested additional options:
A) Strike
This option allows the player to attack with their “precision” score rather than their strength, if you are using this system with player statistics.
STEP ONE: Create variables.
Create the following variables:
%PRECISION: This will keep track of the player’s precision statistic.
STEP TWO: Create & code items.
If you have any weapons (such as the dagger) that you want to be precision-based instead of strength-based, you can adjust the attack code to make this change:
%ATTACK := 1D10 + %MODWEAPON + %PRECISION
STEP THREE: Create “Strike” link.
Create a link titled “strike” on the “melee attack” page, which leads to the “melee attack” page. Paste the following code in the link script:
%ATTACK := 1D10 + %MODWEAPON + %PRECISION
%DODGE := 1D10 + %AGILITY
STEP FOUR: Restrict link.
If you don’t always want this option to be available to the player, you can use link restrictions to restrict it to only specific weapons using the %WEAPONUSED variable.
B) Dodge
This option gives the player a boost to their dodge score at the expense of making an attack. I use it to present the player with additional combat options, such as running away from combat or using the environment to their advantage.
STEP ONE: Create “Dodge” page.
Create a page titled “dodge” with the following flavor text:
“The monster swipes at you with its claws, %%DODGE%<%5%and you wince in pain as it slashes your side.%%%%DODGE%>%4%but you leap away in time.%%”
STEP TWO: Code “Dodge” page script
Paste the following code into the page’s script:
IF %DODGE < 5 THEN %HEALTH := %HEALTH - 1
IF %DODGE < 6 THEN %HEALTH := %HEALTH - 1
IF %DODGE < 7 THEN %HEALTH := %HEALTH - 1
STEP THREE: Create “Dodge” link.
Create a link titled “dodge” on the “melee attack” page and “dodge” page, which lead to the “dodge” page. Paste the following code in the link script:
%DODGE := 1D10 + %AGILITY + 2
This makes the player’s dodge more likely to succeed, and they will be less likely to take damage.
STEP FOUR: Add additional options.
You can now add additional links to the “dodge” page, such as giving the player an “Run” option or, for example, letting them try and throw sand at their opponent as a distraction. You don’t need to include the option to attack on this page, as all the player needs to do to attack is use one of the weapons in their inventory.
C) Run
It’s recommended that you have this option be on the “dodge” page. It gives the player the opportunity to flee combat.
STEP ONE: Create variables.
Create the following variables:
%RUN: This will keep track of whether the player’s escape attempt is successful or not.
STEP TWO: Create new pages.
Create two new pages, one titled “Escape successful” and one titled “Blocked by monster”.
STEP THREE: Code page script.
Paste the following into the page script for “Escape successful”:
%BATTLE := 0
This will ensure that the game exits combat mode once the player has escaped.
Paste the following into the page script for “Blocked by monster”:
IF %DODGE < 5 THEN %HEALTH := %HEALTH - 1
IF %DODGE < 6 THEN %HEALTH := %HEALTH - 1
IF %DODGE < 7 THEN %HEALTH := %HEALTH - 1
STEP FOUR: Write flavor text.
On the “Escape successful” page, write a short description of the player escaping the monster and present them with their new options now that they’ve escaped.
On the “Blocked by monster” page, paste the following text:
“Unfortunately the monster is too quick, and it moves between you and the exit, blocking your escape.
The monster swipes at you with its claws, %%DODGE%<%5%and you wince in pain as it slashes your side.%%%%DODGE%>%4%but you leap away in time.%%”
STEP FIVE: Create “Run” link.
Create a link titled “run” on the dodge page. Have its destination be “Escape successful”. Paste the following code in the link script:
%DODGE := 1D10 + %AGILITY
%RUN := 1D10 + %AGILITY
IF %RUN < 5 THEN $DEST := @P(Blocked by monster)
This makes it so that if the player rolls well their escape is successful, if not, it is not. You can adjust the threshold to make it harder or easier to escape combat.
If you are using the armor customization option, it is strongly recommended that you swap out the %RUN calculation for the following:
%RUN := 1D10 + %AGILITY + %MODWEIGHT
D) And more!
You can add any option you can think of, but here are some ideas:
-Taking advantage of a terrain feature or high ground for an attack bonus.
-Attempting to disarm your opponent after making a “Strike” attack.
-Firing with a ranged weapon from an unusual location.
Adding options like this is what will make your combat dynamic rather than point and click. However, each option you add creates a new page, with new options that need to be coded onto it and so on, increasing the time commitment. In order to reduce the amount of time you spend coding links, it’s recommended that you make the “dodge” option available on every page, and other special options available only on certain pages, such as making “run” or “create distraction” available on the “dodge” page, and options such as “disarm your opponent” or “target your opponent’s weak spot” available only after the player has used the “strike” option.
4) Ranged weaponry
If you want to include ranged weapons, such as a longbow, you can.
STEP ONE: Create variables.
Create the following variables:
%ARROWS: This keeps track of how many arrows the player has. Set it to 12.
%ARROWFIRED: This keeps track of how many arrows the player has fired, so they can retrieve them after combat.
STEP TWO: Create & code items.
Create an item titled “Longbow” and paste in the following script:
IF %ARROWS < 1 THEN $DEST := @P(Out of arrows)
%MODWEAPON := 1
%WEAPONUSED := 6
%ARROWS := %ARROWS - 1
%ARROWFIRED := %ARROWFIRED + 1
%ATTACK := 1D10 + %MODWEAPON + %PRECISION
%DODGE := 1D10 + %AGILITY
IF %BATTLE = 1 THEN $DEST := @P(ranged attack)
STEP THREE: Code page script.
Create a page titled “Ranged attack” and paste the following into the page script:
IF %ATTACK > 4 THEN %MOBLIFE01 := %MOBLIFE - 1
IF %ATTACK > 5 THEN %MOBLIFE01 := %MOBLIFE - 1
IF %ATTACK > 6 THEN %MOBLIFE01 := %MOBLIFE - 1
IF %DODGE < 5 THEN %HEALTH := %HEALTH - 1
IF %DODGE < 6 THEN %HEALTH := %HEALTH - 1
IF %DODGE < 7 THEN %HEALTH := %HEALTH - 1
Now that you have a new page, you’ll need to code your alternative combat options (such as “dodge”) onto this page as well.
You may also want to set %ARROWFIRED to 0 at the start of combat, if your game gives players the option to fire the longbow outside of combat.
Create a page titled "Out of arrows." Include on this page a short description of the player realizing their quiver is empty, and a "previous page" link for them to return to the game. On the "previous page" link, set %ATTACK to 0 and %DODGE to 10 so that no damage is dealt when they return to their page.
STEP FOUR: Write flavor text.
“You fire your bow at the monster, %%ATTACK%>%4%shooting it in the side and drawing blood.%%%%ATTACK%<%5%but your arrow flies past it.%%
The monster swipes at you with its claws, %%DODGE%<%5%and you wince in pain as it slashes your side.%%%%DODGE%>%4%but you leap away in time.%%”
STEP FIVE: Adjust combat ending.
On the “Monster defeated” page, and any other page where combat ends (such as “escape successful”) you’ll need to paste the following into the page script:
%ARROWFIRED := 0
On the “Monster defeated” page, where the player has the opportunity to collect their arrows, you’ll need to paste the following:
%ARROWS := %ARROWS + %ARROWFIRED
%ARROWFIRED := 0
They need to go in that order, or the player won’t get any arrows back. You may want to have some arrows be broken or destroyed in combat. This can be done with the following code:
%ARROWFIRED := %ARROWFIRED - 1D3
IF %ARROWFIRED < 0 THEN %ARROWFIRED := 0
%ARROWS := %ARROWS + %ARROWFIRED
%ARROWFIRED := 0
5) Armor and the “Block” variable
If the player has the option to collect armor throughout the game, it can be used in combat to help them avoid taking damage.
STEP ONE: Create variables.
Create the following variables:
%BLOCK: This will be used to keep track of the player’s resistance to damage round-to-round.
%MODARMOR: This is used to track how good the player’s armor is. It should already have a value before combat begins, depending on what the player’s armor is.
%MODWEIGHT: This is used to track how heavy the player’s armor is. It should already have a value before combat begins, depending on what the player’s armor is. It should be negative if the player is wearing any.
STEP TWO: Edit item and link scripts.
For every item and link where the code surrounding the %DODGE variable appears, replace it with the following:
%DODGE := 1D10 + %MODWEIGHT + %AGILITY
%BLOCK := 1D10 + %MODARMOR
Now, dodge is penalized if the player is wearing armor, as %MODWEIGHT will be negative.
STEP THREE: Code page script.
On each page script where the code surrounding the dodge variable appears, replace it with the following:
IF %DODGE < 7 THEN
BEGIN
IF %BLOCK < 6 THEN %HEALTH := %HEALTH - 1
IF %BLOCK < 7 THEN %HEALTH := %HEALTH - 1
IF %BLOCK < 8 THEN %HEALTH := %HEALTH - 1
END
This makes it so that if the player’s %DODGE value is below 7, they then check their %BLOCK value to see if they take damage, or if the blow is absorbed by their armor. In this example, if %BLOCK is above 7 for that round, they player does not take any damage.
Since the player now has two levels of defense against taking damage, it should be proportionally harder for them to block damage. Adjust the thresholds for %DODGE and %BLOCK as needed.
6) Identical combats
If the player later ends up fighting an identical opponent, you can simply route them back to the same battle sequence by having the destination for that combat’s %BATTLE value be the same. You’ll need to ensure that the player gets routed back onto the main path with $DEST variables afterward.
If the player ends up fighting a monster with the same difficulty but different flavor text, you can still do this by adjusting the page’s flavor text in the following way:
“You slash your [weapon] at the %%BATTLE%=%1%goblin%%%%BATTLE%=%2%orc%%, %%ATTACK%>%4%striking it in the side and drawing blood.%%%%ATTACK%<%5%but it dodges your strike.%%
The %%BATTLE%=%1%goblin%%%%BATTLE%=%2%orc%% swipes at you with its sword, %%DODGE%<%5%and you wince in pain as it slashes your side.%%%%DODGE%>%4%but you leap away in time.%%”
You’ll need to ensure there are no bugs surrounding %MOBLIFExx variables and flavor text.
