Recent Posts

Filtering Ecto with a Behaviour

Posted on 02 Feb 2018

For my project ExVenture I wanted to have a very nice admin interface and with that comes filtering of tables. This is what I came up with, which I think has been very extendable and worked out well.

This is what we'll end up with:

Web.Admin.ItemController

Let's first start at a controller to see what it looks like there. The controller is incredibly simple, pulling out the filter parameters and passing it into a web specific module, Web.Item. You can view the full file here on github.

def index(conn, params) do
  %{page: page, per: per} = conn.assigns
  filter = Map.get(params, "item", %{})
  %{page: items, pagination: pagination} = Item.all(filter: filter, page: page, per: per)
  conn |> render("index.html", items: items, filter: filter, pagination: pagination)
end

This also includes my pagination module, but I will be glossing over that part. We will see it again in the Web.Item module.

Web.Item

Next let's look at the Web.Item module. This module contains the all/1 function used above. It implements the Filter's behaviour that requires a single function filter_on_attribute/2.

The map of filters passed in from the controller is looped over and passed into this function of the module. Inside the filter_on_attribute/2 function you can tweak the query to do whatever is needed to perform a filter based on that attributes.

defmodule Web.Item do
  alias Data.Item
  alias Web.Filter

  @behaviour Filter

  @doc """
  Load all items
  """
  @spec all(Keyword.t()) :: [Item.t()]
  def all(opts \\ []) do
    opts = Enum.into(opts, %{})

    Item
    |> order_by([i], i.id)
    |> preload([:item_aspects])
    |> Filter.filter(opts[:filter], __MODULE__)
    |> Pagination.paginate(opts)
  end

  @impl Filter
  def filter_on_attribute({"level_from", level}, query) do
    query |> where([i], i.level >= ^level)
  end

  def filter_on_attribute({"level_to", level}, query) do
    query |> where([i], i.level <= ^level)
  end

  def filter_on_attribute({"tag", value}, query) do
    query |> where([n], fragment("? @> ?::varchar[]", n.tags, [^value]))
  end

  def filter_on_attribute(_, query), do: query
end

You can see here that I'm doing a fragment to look into an array of strings. You could also do a join or other more complicated query manipulation.

Web.Filter

Finally the Web.Filter module itself. This is very simple, it defines a callback and a single function. The function also requires the using module to be passed in as the last argument. This is very simple with the __MODULE__ macro.

defmodule Web.Filter do
  @moduledoc """
  Filter an `Ecto.Query` by a map of parameters. Modules
  that use this should follow it's behaviour.
  """

  @doc """
  This will be reduced from the query params that are
  passed into `filter/3`.
  """
  @callback filter_on_attribute(
              {attribute :: String.t(), value :: String.t()},
              query :: Ecto.Query.t()
            ) :: Ecto.Query.t()

  @doc """
  Common elements of filtering a query
  """
  @spec filter(Ecto.Query.t(), map(), atom()) :: Ecto.Query.t()
  def filter(query, nil, _), do: query

  def filter(query, filter, module) do
    filter
    |> Enum.reject(&(elem(&1, 1) == ""))
    |> Enum.reduce(query, &module.filter_on_attribute/2)
  end
end

There are two other small things that this does, it pattern matches on a nil map and simply passes the query through. Lastly it filters out values that are an empty string since that is an empty form field.

The Template

I won't go into detail about this, but you can view it on github.

Conclusion

This has worked out really well in crafting my admin panel. Adding a new filter is as simple as adding the template code and a single function, no extra magic needed.

ExVenture Updates for January 2018

Posted on 23 Jan 2018

The last month of ExVenture had some big additions. New are NPC conversations and questing, along with other small tweaks to make NPCs feel more part of the world.

The documentation website is exventure.org. You can see the latest additions here on midmud, my running instance of ExVenture.

Stickers

I got stickers for midmud within the last week.

Stickers

NPC Conversations and Scripts

NPCs now have a script that will let players whisper to them and respond with. An example interaction is as follows:

You greet Guard
Guard replies, "Hello, are you here to find out about our bandit problem?"
You tell Guard, "huh?"
Guard replies, "I don't know about that, but I can help you with bandits",
You tell Guard, "yes"
Guard replies, "I heard they are hiding down in a cave."
You have a new quest.

You can find more about the format at exventure.org.

Questing

The even bigger feature is questing. NPCs can hand out quests as seen above in the example conversation. Quests replace the default NPC script if a quest is available for a player. A player doesn't necessarily get a quest when conversing with an NPC that is trying to give one out. They must hit an end of the conversation that has a trigger: quest.

You can see more about questing at exventure.org.

Handing out a quest

Quests currently can require items or NPCs to be killed in order to trigger them. NPCs are tracked and counted when they are killed by a player. Items are removed when turning in the quest. Quests can also be in a quest chain, requiring parents to be completed before being offered children quests. This can create a linear story that helps move a player through an area.

NPC status line

NPCs now have a status line that displays instead of {name} is here. This area will also display if the NPC is a quest giver so players know to greet them to start a quest.

NPC status

Note Pad

There is a general note pad area now. Notes are simple records that have a name and a body that displays as markdown. I wanted to have something where I could record more free form ideas about the game that I could come back to later.

Mail system

A mail system is currently being worked on, before I was distracted by questing. Right now it is read only in the game, but you can view and read mail if you have one.

Small tweaks

  • Removed a lot of passing around of the session pid
  • Start running some of the modules through the elixir formatter
  • Tweak NPC death
  • Giving a reason for leaving or entering a room
  • NPCs have a status line and description now
  • Look at items, players, npcs
  • Basic session statistics are stored: how long, what commands were used
  • Color codes don't for an early wrap, no longer leaving odd length lines

Next Month

I have a few ideas on how to rework the class and skill system. I might get rid of classes as a rigid architype after reading Designing Virtual Worlds by Richard Bartle. He talks about having an initial class system be a starting point of skills and being free form from there. That way new players can instantly get started with minimal thinking and then later on they can completely change what they want to be. This has slowly grown on me and I really like the idea of it.

I would also like to finish the mail system.

A Tweak to Phoenix Contexts

Posted on 10 Jan 2018

I would like to start this post out by saying this isn't a negative post against the bounded context approach Phoenix is now geared towards. I wanted to showcase what has worked out really well with my side project, ExVenture, which has grown to a fairly hefty size. As always you can see the source on GitHub and a running instance at MidMUD.

So what do you have instead?

Instead of the context approach where everything is hidden beneath the context I instead have several separate module namespaces that are my "contexts". Here is my lib folder structure:

lib/
├── data
├── ex_venture
├── game
├── metrics
├── networking
└── web

Each of those top level folders are a loose context.

Data.*

This level contains all of my ecto schemas and modules that deal with data.

lib/data/
├── bug.ex
├── class.ex
├── config.ex
├── effect.ex
├── event.ex
└── ...

Game.*

This level contains what I would call the business logic of the app. It has all of the user processing commands, gen servers, and is the core of the app.

lib/game/
├── command
├── command.ex
├── format
├── format.ex
├── item.ex
├── npc
├── npc.ex
├── room
├── room.ex
├── session
├── session.ex
└── ...

Inside this namespace I also split into more sub modules based in general on GenServer processes. For instance Game.Session has a lot of sub modules to help create a session process for when someone starts playing the app. This is fairly close to the general theme of the Bounded Contexts in Phoenix.

Metrics.*

This level contains all of my Prometheus metrics modules and is fairly slim.

Networking.*

This level contains telnet related modules, including the ranch protocol.

Web.*

This level contains the Phoenix layer. I should note that I consider ExVenture to be an OTP app first, and a Phoenix app a distant second.

lib/web
├── bug.ex
├── channels
├── class.ex
├── config.ex
├── controllers
├── endpoint.ex
├── filter.ex
├── gettext.ex
├── item.ex
├── npc.ex
├── pagination.ex
├── plug
├── prometheus_exporter.ex
├── room.ex
├── router.ex
├── supervisor.ex
├── templates
├── user.ex
├── views
└── ...

Small aside: I really like naming this module Web and not ExVentureWeb or similar, it really helps out my tab complete habit to be simply named Web.

How This All Fits Together

So with all of these different modules as contexts, how does this all fit together? I will show this by giving an example of the NPC (the non-player characters in the game) slice.

Data.NPC

This module is a simple ecto schema, it simply validates the data in a changeset.

Game.NPC

This is a GenServer process for the NPC. It's a mix of an NPC struct and an NPC Spawner struct. I have a lot of sub modules for this dealing with events that the NPC may act on, respawning if it is killed, and other helper modules like the Supervisor for NPCs.

Web.NPC

The web module is a helper module to fit between the Phoenix layer and the core of my app. All of the controllers deal with this module and not a deeper part of the app. It handles creating NPCs, their spawners, adding items, and ensuring the live processes are kept up to date as all of these changes happen. This is probably the closest thing to a standard Phoenix context that I have.

Conclusion

As you can see what I ended up with is only a slight tweak on the general principles behind Bounded Contexts.

I like having a general schema area and making sure nothing else goes in there. I like having a lot of modules that are related to the process they're attached to. I really like having the web layer barely know about the core of the app.

I hope this helps make you think about the structure of your app more and realize that bounded contexts are there to make you think about your app, and not be the only way.

ExVenture Updates for December 2017

Posted on 26 Dec 2017

The last month of ExVenture mostly saw behind the scenes updates. Lots of small tweaks here and there in the admin interface along with documentation of modules and functions.

The documentation website is exventure.org. You can see the latest additions here on MidMUD, my running instance of ExVenture.

Effects updates

Items that you are wielding are now included in the effects calculation. So if you use a dagger to use a magic skill, the dagger's damage will also be included, but the magic damage can be halved due to a damage/type restriction on the dagger. So wielding the correct weapons will help maximize your damage output.

Also new are continuous damage effects, damage/over-time. These deal immediate damage and then tick every milliseconds, up to a maximum count. This can be used for things like poison.

{
  'kind': 'damage/over-time',
  'type': 'slashing',
  'amount': 10,
  'every': 1000,
  'count': 4
}

Finally there is a recover effect that healing was converted to. This is a more generic version that can recover skill points and move points along with health points.

Pagination and filtering

A lot of the admin sections now paginate and have a filter on the side for searching. This started to become required as I filled in more things in MidMUD. Here is the NPC admin:

NPC Admin Filtering

User admin

The User admin got some sprucing up, the index has pagination and filtering now along with displaying more information. The show for a user displays about the same information but does it in a lot nicer way. When someone is signed in you can also see live stats such as which room they are in.

User Admin Index

User Admin Show

Item Admin

I've recently put a lot of work into the item admin. I want to have a more filled in world as people start stumbling across the game. The items index was a simple list before adding fitlering to it. I also renamed ItemTag to ItemAspect to allow a normal tags field to sit on items. Item cloning was also added (pre-fill the new form) to help speed up sets of items, such as a full leather armor set.

Item Admin Index

Use items

A new command was added use which uses an item in your inventory on yourself. There is no ability to target yet, it simply applies the effects to yourself, good or bad. That means you can use sword on yourself and take damage.

Shop command interface

I log commands that people try to use and get a parse error. A lot of these were related to the shops command. I tried updating that to make it more usable. Most interfacing with shops will now be a lot more smooth when there is only one shop is the room. I also added a final parse catch to display help information if the command starts with shop. Hopefully there will be less troubles with this part of the game in the future.

Small tweaks

  • Game inventory collapses duplicate items
  • Edit game name and MOTD from the web panel
  • Slightly nicer prompt output for dealing continuous effects/using effects

Social Updates

I posted about someone finding the game and playing around for 15+ minutes on twitter, and included a photo of their stats. That was retweeted by @elixirlang and a lot of people found the project because of it. Welcome new people!

Next Month

I will copy last months goals here as I didn't get around to doing a range of damage. I have a few small tweaks I'd like to make, such as mass adding spawners. For a big goal I think adding in a general item listing to the public side of the app would be good. I think it makes sense to add it in because you can view the stats of any item in World of Warcraft, so letting people look around for cool things to hunt out seems like a good addition.

ExVenture Updates for November 2017

Posted on 28 Nov 2017

The last month for ExVenture has seen a lot of NPC changes and lots of documentation. The documentation website is exventure.org. You can see the latest additions here on MidMUD, my running instance of ExVenture.

NPC Events

I have expanded a lot on the event system for NPCs. You can see a full list at exventure.org.

NPCs wandering around, and triggering aggro

The most exciting thing that happened was NPCs can now fight back! They will also wander around near where they spawned and aggro players if they stumble into any. This is all stored and edited in a huge JSON array right now, but I would like to eventually make it a nice interface. This is the bandit's events on MidMUD:

[
  {
    "type": "room/entered",
    "action": {
      "type": "target"
    }
  },
  {
    "type": "combat/tick",
    "action": {
      "weight": 10,
      "type": "target/effects",
      "text": "{user} slashes at you.",
      "effects": [
        {
          "type": "slashing",
          "kind": "damage",
          "amount": 2
        }
      ],
      "delay": 2.0
    }
  },
  {
    "type": "tick",
    "action": {
      "type": "move",
      "max_distance": 2,
      "chance": 25
    }
  }
]

Documentation

I have finished a first pass at the documentation site. All of the large systems in the admin panel have documentation at this point. There are still a few small things with rooms and NPCs that need documentation.

Item instances

Items now create instances, and are tracked as such. This allows extra data to hang out with the item id. Right now only created_at is included with the id.

Minor Tweaks

A few minor tweaks that make life nicer:

  • Registration can be via the web
  • Registration will display errors if any come up
  • Commands parse a little better, backend code could be deduplicated
  • Common mistakes such as kill target and point users towards the help system
  • Set a target when using a skill, magic missile target
  • Ask for optional email, and allow registering via the home page

Next Month

Next month I'd really like to continue with combat. Right now there is a static amount of damage you will do, it might be nice to do a range of damage. I also want to add in some kind of dodge mechanic. Items also don't affect combat at all either.

Eric Oestrich
I am:
All posts
Creative Commons License
This site's content is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License unless otherwise specified. Code on this site is licensed under the MIT License unless otherwise specified.