DEV Community: Ben Pollard

Ktvn: A library for developing visual novels in Kotlin

Ben Pollard — Tue, 06 Feb 2024 07:50:46 +0000

For a while I've been working on Ktvn, a framework for creating visual novels in Kotlin.

With Ktvn I tried to create a DSL that felt natural and clean to use. Here's an example scene:

internal fun onTheLaunchPad(): Scene {
    return scene {
        this name "On the launch pad"
        this background shuttleDay
        this music shuttleDayMusic
        this layout createLayout {
            this addLeftOf sophie
            this addRightOf toki
            this configure configuration.gameAdapter.layoutAdapter
        }
        this steps listOf(
            next {
                layout moveCenter sophie
                sophie looks normal
                sophie says "Where has that fool gotten to now?"
            },
            next { audio sfx sfxWoosh },
            next {
                layout moveLeft sophie
                layout moveRight toki
                toki looks normal
                toki says "Here I am!"
                toki says "Ready for duty!"
            },
            next {
                sophie looks happy
                sophie says "Ever the fool."
            }
        )
    }
}

For those interested here is a quick guide to getting started.

Adding the package to your project

You need to pull Ktvn into your project. The easiest way to do this is to add the package. The latest package and installation instructions are available here.

First Visual Novel

Once the package has been installed it's time to jump in and start building your first visual novel.

Setup

To start with create a new Console application. It should look something like this:

package com.github.benpollarduk.ktvn.gettingstarted

fun main(args: Array<String>) {

}

Adding the GameEngine

Every Ktvn game requires a GameEngine. The only engine currently included in the Ktvn core library is AnsiConsoleGameEngine. This engine allows a visual novel to be executed on an ANSI compatible console.

val engine = AnsiConsoleGameEngine()

Adding the GameConfiguration

Every Ktvn game requires a GameConfiguration. The configuration ties together many of the concepts required to execute a game. For nearly all applications the DynamicGameConfiguration is a good match because it allows
properties to be specified after its instantiation. Let's add one in the main function and apply the engine.

val configuration = DynamicGameConfiguration().also {
    it.engine = engine
}

Adding a Character and a Narrator

All visual novels will require at least a Narrator or a Character to tell the story. Let's add one of each to the main function, after the engine.

val ben = Character("Ben", configuration.gameAdapter.characterAdapter)

Here I've added a character called Ben (of course) and specified that the adapter is provided by the configuration.
The adapter allows the Character to interact with the engine.

Next I'll add a Narrator.

val narrator = Narrator(configuration.gameAdapter.narratorAdapter)

I've specified that the adapter is provided by the configuration. The adapter allows the Narrator to interact with the engine.

Creating a basic visual novel structure

The next thing to do is to add the structure of the novel itself. We can use the DSL to simplify the process. To start with, let's add a story in the main function. The story will only contain a single chapter, which contains a single scene.

val story = story {
    this add chapter {
        this add scene {

        }
    }
}

Story, Chapter and Scene can all have a name, lets name the scene.

val story = story {
    this add chapter {
        this add scene {
            this name "Welcome to Ktvn"
        }
    }
}

Each scene that contains Characters should have a layout to help with the positioning of characters. The layout needs to be configured so that the game engine can respond to character movements.

val story = story {
    this add chapter {
        this add scene {
            this name "Welcome to Ktvn"
            this layout createLayout {
                this configure configuration.gameAdapter.layoutAdapter
            }
        }
    }
}

Adding some steps

Each scene can contain one or more steps. Let's add a simple step to introduce the story.

val story = story {
    this add chapter {
        this add scene {
            this name "Welcome to Ktvn"
            this layout createLayout {
                this configure configuration.gameAdapter.layoutAdapter
            }
            next { narrator narrates "Welcome to the story!" }
        }
    }
}

Next, we could move the character in to view.

val story = story {
    this add chapter {
        this add scene {
            this name "Welcome to Ktvn"
            this layout createLayout {
                this configure configuration.gameAdapter.layoutAdapter
            }
            next { narrator narrates "Welcome to the story!" }
            next { layout moveLeft ben }
        }
    }
}

And then we can make the character speak.

val story = story {
    this add chapter {
        this add scene {
            this name "Welcome to Ktvn"
            this layout createLayout {
                this configure configuration.gameAdapter.layoutAdapter
            }
            next { narrator narrates "Welcome to the story!" }
            next { layout moveLeft ben }
            next { ben says "Hi." }
        }
    }
}

And then make the character smile.

val story = story {
    this add chapter {
        this add scene {
            this name "Welcome to Ktvn"
            this layout createLayout {
                this configure configuration.gameAdapter.layoutAdapter
            }
            next { narrator narrates "Welcome to the story!" }
            next { layout moveLeft ben }
            next { ben says "Hi." }
            next { ben looks happy }
        }
    }
}

There is much more that can be done, but this is a simple example just to get started.

Executing the game

There is a small amount to do to make the story executable. First, it needs to be wrapped in to a VisualNovel. Then a new Game needs to be made from the VisualNovel so that the story can be executed.

val novel = VisualNovel.create(story, configuration)
val exampleGame = Game(novel)

The GameExecutor class can execute instances of Game. Games can be executed either synchronously or asynchronously.

GameExecutor.executeAysnc(exampleGame)

A quirk of the AnsiConsoleEngine is that we need to start processing the input from the standard input to be able to interact with the game. We will need to stop processing this input when the game execution ends. We will start processing the input when the game begins and stop when execution finishes.

GameExecutor.executeAysnc(exampleGame) {
        engine.endProcessingInput()
    }

engine.beginProcessingInput()

Bringing it all together

That was a lot to go through, but results in only a small amount of code. It should look like this:

package com.github.benpollarduk.ktvn.getting.started

import com.github.benpollarduk.ktvn.characters.Character
import com.github.benpollarduk.ktvn.characters.Emotions.happy
import com.github.benpollarduk.ktvn.characters.Narrator
import com.github.benpollarduk.ktvn.layout.Layout
import com.github.benpollarduk.ktvn.layout.Layout.Companion.createLayout
import com.github.benpollarduk.ktvn.logic.Game
import com.github.benpollarduk.ktvn.logic.GameExecutor
import com.github.benpollarduk.ktvn.logic.VisualNovel
import com.github.benpollarduk.ktvn.logic.configuration.DynamicGameConfiguration
import com.github.benpollarduk.ktvn.logic.engines.ansiConsole.AnsiConsoleGameEngine
import com.github.benpollarduk.ktvn.structure.Chapter
import com.github.benpollarduk.ktvn.structure.Chapter.Companion.chapter
import com.github.benpollarduk.ktvn.structure.Scene
import com.github.benpollarduk.ktvn.structure.Scene.Companion.scene
import com.github.benpollarduk.ktvn.structure.Story
import com.github.benpollarduk.ktvn.structure.Story.Companion.story
import com.github.benpollarduk.ktvn.structure.steps.Then.Companion.next

fun main(args: Array<String>) {
    val engine = AnsiConsoleGameEngine()
    val configuration = DynamicGameConfiguration().also {
        it.engine = engine
    }

    val ben = Character("Ben", configuration.gameAdapter.characterAdapter)
    val narrator = Narrator(configuration.gameAdapter.narratorAdapter)

    val story = story {
        this add chapter {
            this add scene {
                this name "Welcome to Ktvn"
                this layout createLayout {
                    this configure configuration.gameAdapter.layoutAdapter
                }
                next { narrator narrates "Welcome to the story!" }
                next { layout moveLeft ben }
                next { ben says "Hi." }
                next { ben looks happy }
            }
        }
    }

    val novel = VisualNovel.create(story, configuration)
    val exampleGame = Game(novel)

    GameExecutor.executeAysnc(exampleGame) {
        engine.endProcessingInput()
    }

    engine.beginProcessingInput()
}

Simply build and run the application and congratulations, you have a working Ktvn visual novel!

For anyone interested in writing text adventures for .Net...

Ben Pollard — Mon, 05 Feb 2024 23:50:48 +0000

For a while I've been writing a library in C# that simplifies the creation of text adventures and interactive fiction.

Hopefully it's of interest to some of the C# devs on here! Please check out the repo on GitHub and give it a blast!

For those who are interested, here's a quick guide to getting started.

Adding the NuGet package to your project

You will need to pull BP.AdventureFramework into your project. The easiest way to do this is to add the NuGet package. The latest package and installation instructions are available here.

First Game

Once the package has been installed it's time to jump in and start building your first game.

Setup

To start with create a new Console application. Regardless of target framework, it should look something like this:

namespace BP.AdventureFramework.GettingStarted
{
    internal class Program
    {
        private static void Main(string[] args)
        {

        }
    }
}

Adding a PlayableCharacter

Every game requires a character to play as, lets add that next:

private static PlayableCharacter CreatePlayer()
{
    return new PlayableCharacter("Dave", "A young boy on a quest to find the meaning of life.");
}

In this example whenever CreatePlayer is called a new PlayableCharacter will be created. The character is called "Dave" and has a description that describes him as "A young boy on a quest to find the meaning of life.".

Creating the game world

The game world consists of a hierarchy of three tiers: Overworld, Region and Room. We will create a simple Region with two Rooms. We can do this directly in the Main function for simplicity. To start with lets make the Rooms:

private static void Main(string[] args)
{
    var cavern = new Room("Cavern", "A dark cavern set in to the base of the mountain.", new Exit(Direction.North));

    var tunnel = new Room("Tunnel", "A dark tunnel leading inside the mountain.", new Exit(Direction.South));
}

Although the Rooms haven't been added to a Region yet there are exits in place that will allow the player to move between them.

Games are boring without Items to interact with, let's add an item to the tunnel:

var holyGrail = new Item("Holy Grail", "A dull golden cup, looks pretty old.", true);

tunnel.AddItem(holyGrail);

Looking good, but the Rooms need to be contained within a Region. RegionMaker simplifies this process, but sometimes creating a Region directly may be more appropriate if more control is needed. Here we will use RegionMaker:

var regionMaker = new RegionMaker("Mountain", "An imposing volcano just East of town.")
{
    [0, 0, 0] = cavern,
    [0, 1, 0] = tunnel
};

This needs more breaking down. The RegionMaker will create a region called "Mountain" with a description of "An imposing volcano just East of town.". The region will contain two rooms, the cavern and the tunnel. The cavern will be added at position x 0, y 0, z 0. The tunnel will be added at position x 0, y 1, z 0, north of the cavern.

The game world is nearly complete, but the Region needs to exist within an Overworld for it to be finished. We will use OverworldMaker to achieve this:

var overworldMaker = new OverworldMaker("Daves World", "An ancient kingdom.", regionMaker);

This will create an Overworld called "Daves World" which is described as "An ancient kingdom" and contains a single Region.

All together the code looks like this:

var cavern = new Room("Cavern", "A dark cavern set in to the base of the mountain.", new Exit(Direction.North));

var tunnel = new Room("Tunnel", "A dark tunnel leading inside the mountain.", new Exit(Direction.South));

var holyGrail = new Item("Holy Grail", "A dull golden cup, looks pretty old.", true);

tunnel.AddItem(holyGrail);

var regionMaker = new RegionMaker("Mountain", "An imposing volcano just East of town.")
{
    [0, 0, 0] = cavern,
    [0, 1, 0] = tunnel
};

var overworldMaker = new OverworldMaker("Daves World", "An ancient kingdom.", regionMaker);

Checking if the game is complete

For a game to come to an end it needs to reach either a game over state or a completion state.

Firstly lets look at the logic that determines if the game is complete. An EndCheck is required, which returns an EndCheckResult that determines if the game is complete.

In this example lets make a method that determines if the game is complete. The game is complete if the player has the holy grail:

private static EndCheckResult IsGameComplete(Game game)
{
    if (!game.Player.FindItem("Holy Grail", out _))
        return EndCheckResult.NotEnded;

    return new EndCheckResult(true, "Game Complete", "You have the Holy Grail!");
}

If the player has the holy grail then the EndCheckResult will return that the game has ended, and have a title that will read "Game Complete" and a description that reads "You have the Holy Grail!".

A common game over state may be if the player dies:

private static EndCheckResult IsGameOver(Game game)
{
    if (game.Player.IsAlive)
        return EndCheckResult.NotEnded;

    return new EndCheckResult(true, "Game Over", "You died!");
}

Creating the game

The game now has all the required assets and logic it just needs some boilerplate to tie everything together before it is ready to play.

A GameCreationCallback is required to instantiate an instance of a Game. This is so that new instances of the Game can be created as required.

var gameCreator = Game.Create(
    "The Life Of Dave",
    "Dave awakes to find himself in a cavern...",
    "A very low budget adventure.",
    x => overworldMaker.Make(),
    CreatePlayer,
    IsGameComplete,
    IsGameOver);

This requires some breaking down. The Game class has a Create method that can be used to create instances of Game. This takes the following arguments:

Name - the name of the game.
Introduction - an introduction to the game.
Description - a description of the game.
OverworldGenerator - a callback for generating instances of the overworld.
PlayerGenerator - a callback for generating instances of the player.
CompletionCondition - a callback for determining if the game is complete.
GameOverCondition - a callback for determining if the game is over.

Executing the game

The game is executed simply by calling the static Execute method on Game and passing in the game creation callback.

Game.Execute(gameCreator);

Bringing it all together

The full example code should look like this:

using BP.AdventureFramework.Assets;
using BP.AdventureFramework.Assets.Characters;
using BP.AdventureFramework.Assets.Locations;
using BP.AdventureFramework.Logic;
using BP.AdventureFramework.Utilities;

namespace BP.AdventureFramework.GettingStarted
{
    internal class Program
    {
        private static EndCheckResult IsGameComplete(Game game)
        {
            if (!game.Player.FindItem("Holy Grail", out _))
                return EndCheckResult.NotEnded;

            return new EndCheckResult(true, "Game Complete", "You have the Holy Grail!");
        }

        private static EndCheckResult IsGameOver(Game game)
        {
            if (game.Player.IsAlive)
                return EndCheckResult.NotEnded;

            return new EndCheckResult(true, "Game Over", "You died!");
        }

        private static PlayableCharacter CreatePlayer()
        {
            return new PlayableCharacter("Dave", "A young boy on a quest to find the meaning of life.");
        }

        private static void Main(string[] args)
        {
            var cavern = new Room("Cavern", "A dark cavern set in to the base of the mountain.", new Exit(Direction.North));

            var tunnel = new Room("Tunnel", "A dark tunnel leading inside the mountain.", new Exit(Direction.South));

            var holyGrail = new Item("Holy Grail", "A dull golden cup, looks pretty old.", true);

            tunnel.AddItem(holyGrail);

            var regionMaker = new RegionMaker("Mountain", "An imposing volcano just East of town.")
            {
                [0, 0, 0] = cavern,
                [0, 1, 0] = tunnel
            };

            var overworldMaker = new OverworldMaker("Daves World", "An ancient kingdom.", regionMaker);

            var gameCreator = Game.Create(
                "The Life Of Dave",
                "Dave awakes to find himself in a cavern...",
                "A very low budget adventure.",
                x => overworldMaker.Make(),
                CreatePlayer,
                IsGameComplete,
                IsGameOver);

            Game.Execute(gameCreator);
        }
    }
}

Simply build and run the application and congratulations, you have a working BP.AdventureFramework game!