Character Creation

We have a basic server, and basic user/session management. Now players need the ability to create characters.

The Character Model

We can use an Ecto generator to build us a database model and migration for the Character entity. From the web app apps/elixir_mud_web run:

 mix phx.gen.context Characters Character characters\
 name:string\
 player_id:references:players\
 race:enum:human:elf:halfling\
 level:integer

This command generates us a table migration, a new Characters context, and a Character model. Lets modify the migration slightly. We don't want characters to be created without level, name, race, or player. We will prevent null values on name, race, and player_id. For level we can set a default of 1.

defmodule ElixirMud.Repo.Migrations.CreateCharacters do
  use Ecto.Migration

  def change do
    create table(:characters) do
      add :name, :string, null: false
      add :race, :string, null: false
      add :level, :integer, null: false, default: 1
      add :player_id, references(:players, on_delete: :delete_all), null: false

      timestamps()
    end

    create index(:characters, [:player_id])
  end
end

apps/elixir_mud/priv/repo/xxxx_create_characters.exs

Now we can modify the database model. We will add player_id to cast so it can be passed in when creating a character and to validate_required so it must be present. We can also remove level from validate_required since it can be omitted and will default to 1.

defmodule ElixirMud.Characters.Character do
  use Ecto.Schema
  import Ecto.Changeset

  schema "characters" do
    field :name, :string
    field :level, :integer
    field :race, Ecto.Enum, values: [:human, :elf, :halfling]
    field :player_id, :id

    timestamps()
  end

  @doc false
  def changeset(character, attrs) do
    character
    |> cast(attrs, [:name, :race, :level, :player_id])
    |> validate_required([:name, :race,  :player_id])
  end
end

apps/elixir_mud/lib/elixir_mud/characters/character.ex

Form the root of the project migrate the database with:

mix ecto.migrate

Characters Context

The generator gave us some basic management function in characters.ex, but we will need more. Instead of creating all our query logic in the context file we can create reusable query fragments that can be composed into full queries. We will put these in the character.ex model.

First add a few imports and aliases to the top of the module. Aliasing the current module simply gives us the ability to reference it directly instead of using __MODULE__, which looks a bit cleaner.

use Ecto.Schema
import Ecto.Changeset
import Ecto.Query, warn: false
alias ElixirMud.Accounts.Player
alias ElixirMud.Characters.Character

Then, we will add four new query fragment functions:

query_for_player/2 will allow us to query characters for a given player.
query_for_id/2 will allow us to query characters by a character id.
order_name/1 will allow us to order the characters by their name.
query_with_player/1 will allow us to preload the player details when looking up a character.

def query_for_player(query \\ Character, %Player{} = player) do 
  from c in query,
    where: c.player_id == ^player.id
end

def query_for_id(query \\ Character, id) do
  from c in query,
    where: c.id == ^id
end

def order_name(query \\ Character) do
  from c in query,
    order_by: [asc: c.name]
end

def query_with_player(query \\ Character) do
  from c in query,
    join: p in assoc(c, :player),
    preload: [player: p]
end

apps/elixir_mud/lib/elixir_mud/characters/character.ex

Each of these functions take a query as their first parameter and the return a query. This allows them to be chained together to easily make complex queries.

We can modify the generated context functions for characters to use our new composable queries. list_characters/0 should order by name:

def list_characters do
  Character.order_name()
  |> Repo.all()
end