Code Example Battle Scene Mechanics With Hit Points, Attack, Defend & Flee

This is an example of battle or fight scene mechanics code written in pure Ink script. It's fully playable if you copy and paste the code into Inky. It's fully documented with comments inside of the code explaining what each part does. If anything isn't clear, please feel free to leave a reply.

// Initialize variables.
VAR MONSTER_HP = 0
VAR MONSTER_TYPE = ""
VAR PLAYER_HP = 100
VAR IS_DEFENDING = false

// Start the story.
-> first_knot

// Player attacks monster function.
=== function player_attacks(is_attacking)
    ~ temp damage = 0
    // If is_attacking is set to false, the player does not attack the monster.
    {is_attacking:
        ~ IS_DEFENDING = false
        ~ damage = RANDOM(10, 40)
        // Update the monster's hip points after they take damage.
        ~ MONSTER_HP -= damage
    }
    ~ return damage
  
// Monster attacks player function.
=== function monster_attacks(is_attacking)
    ~ temp damage = 0
    // If the player attacks (is_attacking is true), they get hit with the monster's full power.
    {is_attacking:
        ~ damage = RANDOM(20, 40)
        // Update the player's hit points after they take damage.
        ~ PLAYER_HP -= damage
    // If the player selects Defend (is_attacking is false), we minimize the Damage the monster can do.
    - else:
        ~ damage = RANDOM(0, 20)
        // Update the player's hit points after they take damage.
        ~ PLAYER_HP -= damage
    }
    ~ return damage

// Use a Shuffle to randomize where the player is walking.
== first_knot
You're walking {~in the desert|on the beach|on the moon|to work}. You have {PLAYER_HP} hit points.

// Use a Tunnel and a Knot with Parameters to set the battle variables. We only send the Random Minimum and Maximum hit points for the monster, but we could set other Variables here if we wanted to further customize each battle before it starts.
-> set_battle_variables(50,100) ->

+ Keep walking
-> turn_hero

// This is a reusable configuration Knot that allows us to set the parameters of a battle before it starts. We need to set several Variables before we start and not have them reset until the battle is over. We set the Minimum and Maximum hit points for the RANDOM function and we also set a random Monster Type. We could add many more things here, like weapons, difficulty, etc. We use a Tunnel to allow us to visit this Knot and return to where we came from without the player ever seeing anything.
== set_battle_variables(min,max)
~ MONSTER_HP = RANDOM(min,max)
~ temp randMonsterType = RANDOM(1,4)
{
    - randMonsterType == 1: ~ MONSTER_TYPE = "monster"
    - randMonsterType == 2: ~ MONSTER_TYPE = "cat"
    - randMonsterType == 3: ~ MONSTER_TYPE = "giantess"
    - randMonsterType == 4: ~ MONSTER_TYPE = "werewolf"
}
// This sends the game play back to where the tunnel started.
->->

// Player turn.
== turn_hero
Standing directly in front of you is a {MONSTER_TYPE} with {MONSTER_HP} hit points.
Your hit points are {PLAYER_HP} right now.
What will you do?
+ [Attack]
    // We call the Player Attack function.
    You attack the {MONSTER_TYPE} for {player_attacks(true)} damage.
    // If the monster's hit points are zero, send the player to victory.
    {MONSTER_HP <= 0:
        -> monster_defeated
    }
    -> turn_monster
+ [Defend]
    // We call the Player Attack function with the parameter set to false and set IS_DEFENDING to true since the Player is defending, not attacking.
    ~ player_attacks(false)
    ~ IS_DEFENDING = true
    You defend.
    -> turn_monster
+ [Run Away]
    // We send the player to the first knot if they run away.
    You run away until you're too tired to run anymore.
    -> first_knot


// Monster turn.
== turn_monster
// Check if the monster is still alive
{MONSTER_HP > 0:

    // Use a shuffle to vary the text.
    The fearsome creature {~growls|bares its teeth|lunges|rushes toward you}.
    // If the player is defending, we show different text since the player will not attack and it will hit the player for less damage.
    {IS_DEFENDING:
        It tries to attack you, but you're defending! You only take {monster_attacks(false)}.
    - else:
        // If the player was attacking rather than defending, we show the results here.
        The {MONSTER_TYPE} {~attacks you|bites you|slaps you|smacks you} for {monster_attacks(true)}!
            // If the player's hit points are zero or less, send them to the ending.
            {PLAYER_HP <= 0:
        -> player_defeated
    }
}
    // After the monster's turn, continue the battle or go back to the start.
    -> turn_hero
}
// If the monster reaches zero hit points, the player wins this battle.
-> monster_defeated

== monster_defeated
Congratulations! You have defeated the {MONSTER_TYPE}.
// After the monster is defeated, go back to walking.
-> first_knot

== player_defeated
You weren't able to beat the {MONSTER_TYPE}.
-> END

Notes:

1. To understand the above code, you should be familiar with Functions, Variables, Knot Parameters, Shuffles, and Tunnels.
2. The purpose of the "set_battle_variables" knot is to create a reusable configuration knot that you can call with whatever variables you need for any upcoming battle. The config knot uses a tunnel return statement so that it can be called from anywhere in the story using a tunnel statement and then return to wherever it was called from. This configuration example only uses two parameters, but you can use as many as you need: set_battle_variables(min,max,monsterName,monsterLevel,weapon,timeOfDay,etc).
3. There are many different ways to accomplish things in Ink. If this code isn't clear or doesn't do what you need, there many other examples of battle/fight scene mechanics on the web.

Sources: This code is heavily influenced by the work of NovelTech with some parts inspired by The Unofficial Ink Cookbook and other resources.