![Elixir CI Status](

# Kalevala

![Kalevala logo](kalevala.png)

Kalevala is a world building toolkit for text based games, written in Elixir.

## Example Game

There is an example game, Kantele, in the `example/` folder.

To start the game:

cd example/
mix deps.get
mix compile
cd assets/
yarn install
yarn build
cd ..
mix run --no-halt

A telnet listener will start on port `4444` and a TLS listener will start on port `4443` with a self signed cert. A web client will start on port `4500`, visit `http://localhost:4500/` to view it in your browser.

## Components of Kalevala

### Foreman

When you connect, a new `Kalevala.Character.Foreman` process is started. This process handles incoming text from the player, sending out going text and events, and other orchestration.

### Conn

A `Kalevala.Character.Conn` is the context token for controllers and commands. This is similar to a `Plug.Conn`. The main difference being it bundles up multiple renders and events to fire all at once, instead of being used for a single request.

The foreman will generate new `Conn`s before each event or incoming text. After processing the `Conn`, it is processed by sending text to the player and events sent to their router (more on this in a bit).

### Controllers

A `Kalevala.Character.Controller` is the largest building block of handling texting. When starting the foreman, an initial controller is given. This controller is initialized and used from then on. The callbacks required will be called at the appropriate time with a new `Conn`.

Controllers act as a simple state machine, only allowing transitioning to the next one you set in the `Conn`. For instance, you can contain all login logic in a `LoginController`, and handle game commands in its own controller, any paging can be handled in a `PagerController` which can suppress any outgoing text to prevent scrolling while reading, etc.

defmodule Kantele.Character.CommandController do
  use Kalevala.Character.Controller

  require Logger

  alias Kantele.Character.Commands
  alias Kantele.Character.CommandView

  @impl true
  def init(conn), do: prompt(conn, CommandView, "prompt", %{})

  @impl true
  def recv(conn, ""), do: conn

  def recv(conn, data) do"Received - #{inspect(data)}")

    case, data) do
      {:error, :unknown} ->
        |> render(CommandView, "unknown", %{})
        |> prompt(CommandView, "prompt", %{})

      conn ->
      prompt(conn, CommandView, "prompt", %{})

### Commands

A `Kalevala.Character.Command` is similar to a `Controller`, but should be called from a `Controller` through a `Command.Router`. Incoming text can be pattern matched in the router and be processed.

In the example below, you can `, "say hello")` to run the `` function.

defmodule Kantele.Character.Commands do
  use Kalevala.Character.Commands.Router, scope: Kantele

  module(SayCommand) do
    parse("say", :run, fn command ->
      command |> spaces() |> text(:message)

defmodule Kantele.Character.SayCommand do
  use Kalevala.Character.Command

  def run(conn, params) do
    params = %{
      "name" => character(conn).name,
      "message" => params["message"]

    |> render(SayView, "echo", params)
    |> event("room/say", params)

### Views

A `Kalevala.Character.View` renders text and out of band events to the player. These are strings, IO data lists, or `Kalevala.Character.Conn.Event` structs (which are used for GMCP in telnet.)

The sigil `~i` keeps a string as an IO data list, which is faster for processing and should be used if any interpolation is needed. Larger views can use the sigil `~E` to use EEx.

defmodule Kantele.Character.SayView do
  use Kalevala.Character.View

  import IO.ANSI, only: [reset: 0, white: 0]

  def render("echo", %{"message" => message}) do
    ~i(You say, "\e[32m#{message}\e[0m"\n)

  def render("listen", %{"character_name" => character_name, "message" => message}) do
    ~i(#{white()}#{character_name}#{reset()} says, "\e[32m#{message}\e[0m"\n)

### Events

A `Kalevala.Event` is an internal event passed between processes. Events have three fields, which pid is generating the event, the topic (e.g. `room/say`), and a map of data. Controllers and commands can generate events which will get sent to an event router process, which is typically the room they are in.

The `Kalevala.World.Room` process handles the event by running the event through a similar router to command processing. The `Foreman` process handles events with its own event router.

In the example below, you can call the event router with an event of topic `room/say` to run the `` function.

defmodule Kantele.World.Room.Events do
  @moduledoc false

  use Kalevala.Event.Router

  scope(Kantele.World.Room) do
    module(NotifyEvent) do
      event("room/say", :call)

defmodule Kantele.World.Room.NotifyEvent do
  import Kalevala.World.Room.Context

  def call(context, event) do
    Enum.reduce(context.characters, context, fn character, context ->
      event(context,, event.from_pid, event.topic,

### Actions

A `Kalevala.Character.Action` is a small set of functionality that a character can perform. Think of this as an "atom" building block that you can piece together other commands and the behavior tree below together with.

Actions have a single function `run/2`. They accept a `conn` and `params` as commands and controllers do.

The example below bundles together what it means to speak into a channel, e.g. the room your character is in.

defmodule Kantele.Character.SayAction do
  @moduledoc """
  Action to speak in a channel (e.g. a room)

  use Kalevala.Character.Action

  alias Kantele.Character.SayView

  @impl true
  def run(conn, params) do
    |> assign(:text, params["text"])
    |> render(SayView, "echo")
    |> publish_message(params["channel_name"], params["text"], [], &publish_error/2)

  def publish_error(conn, _error), do: conn

### Character "Brains" - Behavior Tree

In order to create non-player characters, you can equip them with a brain of sorts. This comes in the form of a simple behavior tree. The tree evaluates an incoming event and checks to see which branches/leaves trigger.

#### Selectors

- `FirstSelector`, starts at the top and tries each node, continuing until the first node succeeds
- `ConditionalSelector`, starts at the top and tries each node, continuing as long as nodes succeed
- `RandomSelector`, selects a random node to process
- `Sequence`, starts at the top and runs each node, ignoring failing nodes

#### Leaves

- `Condition`, a node that evaluates the condition, if the condition is `false`, then the node fails, generally this is matched with a `ConditionalSelector` at the start to fail the actions below it
- `Action`, a node that will append an action to the conn to be performed, optionally delayed
- `NullNode`, a no-op node that can be used as an empty brain to skip node operation

#### Conditions

- `MessageMatch`, built-in condition to match a `Kalevala.Event.Message` event
- `EventMatch`, built-in condition to match a base `Kalevala.Event` event

### Communication & Channels

A `Kalevala.Communication.Channel` is a pub/sub for sending chat messages between characters. Channels are registered with a callback module, allowing for callbacks before subscriptions/unsubscriptions/publishes.

For instance, rooms can register a channel for themselves, and as characters move around they can change room subscriptions. A `say` command can then publish to this room, with every other character in the room receiving the event via their subscription. Another example might be a global channel that all characters are subscribed to, or one for a set of characters.

By default, the `use` macro will fill in default implementations that allow all.

defmodule Kantele.Communication.BroadcastChannel do
  use Kalevala.Communication.Channel

defmodule Kantele.Communication do
  @moduledoc false

  use Kalevala.Communication

  @impl true
  def initial_channels() do
    [{"general", Kantele.Communication.BroadcastChannel, []}]

### The World

The world in Kalevala consists of `Kalevala.World.Zone`s and `Kalevala.World.Room`s. A zone contains many rooms, and rooms are the basic block of traversing the world. Rooms also act as the primary point of work (processing events) as all events will go through the room that characters are in.

The example game boots the world from flat files, but world data can come from any source as long as the structures can be created. For instance, you might load a simple zone struct with a database ID and hydrate the zone after the process started.