A D&D Encounter Calculator in Elixir

As you may know, I have been running a D&D campaign since December 2025. Because I follow a low-prep, very improvised style, one of the things I needed most was to gauge the difficulty of an encounter on the fly. The Dungeon Master’s Guide has a handy algorithm to calculate the difficulty of an encounter given the player level and the difficulty class of the foes. Unfortunately I’m not fast enough to do that on my mind in the midst of a session whenever a patrol of four duck guardians jump out of a dark alley. So I decided to make a script that will take a string like -m 6:1/8 1 -p 4 4 4 and spit out the experience end the estimated difficulty level.

I could have done that in a billion languages, but here we get to the second part of the story: I am studying Elixir and this script was a perfect candidate as a coding exercise.

I was always fascinated by Elixir, as I find it very elegant and it maps extremely well to my mental model. At the time, though, the fact that it was a dynamically typed language was a bit of an annoyance on a medium project I was working on. I ended up shelving the language in the same bucket where I put Racket: languages I use when I want something fancy for some small script.¹

Recently, the Elixir team has done an incredible job adding gradual typing to the language (as you can see here and here). This pushed me to re-learn it, and so far, there is very little I don’t like.

Anyway, because in the last five months I have used it more often than any other automation script (for TTRPGs), I thought it was worth sharing with you.

There are probably some web pages that can do the same, and better, in a more user-friendly way. But this is my solution, and it is special to me! 😆

Latest version on tangled.org

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
#!/usr/bin/env elixir

defmodule EncounterDifficulty do
  @moduledoc """
  D&D 5e Encounter Difficulty Calculator

  Calculates encounter difficulty based on party composition and monster CRs.
  """

  # XP Thresholds by Character Level: %{level => {easy, medium, hard, deadly}}
  @xp_thresholds %{
    1 => {25, 50, 75, 100},
    2 => {50, 100, 150, 200},
    3 => {75, 150, 225, 400},
    4 => {125, 250, 375, 500},
    5 => {250, 500, 750, 1100},
    6 => {300, 600, 900, 1400},
    7 => {350, 750, 1100, 1700},
    8 => {450, 900, 1400, 2100},
    9 => {550, 1100, 1600, 2400},
    10 => {600, 1200, 1900, 2800},
    11 => {800, 1600, 2400, 3600},
    12 => {1000, 2000, 3000, 4500},
    13 => {1100, 2200, 3400, 5100},
    14 => {1250, 2500, 3800, 5700},
    15 => {1400, 2800, 4300, 6400},
    16 => {1600, 3200, 4800, 7200},
    17 => {2000, 3900, 5900, 8800},
    18 => {2100, 4200, 6300, 9500},
    19 => {2400, 4900, 7300, 10900},
    20 => {2800, 5700, 8500, 12700}
  }

  # XP by Challenge Rating
  @cr_xp %{
    "0" => 10,
    "1/8" => 25,
    "1/4" => 50,
    "1/2" => 100,
    "1" => 200,
    "2" => 450,
    "3" => 700,
    "4" => 1100,
    "5" => 1800,
    "6" => 2300,
    "7" => 2900,
    "8" => 3900,
    "9" => 5000,
    "10" => 5900,
    "11" => 7200,
    "12" => 8400,
    "13" => 10000,
    "14" => 11500,
    "15" => 13000,
    "16" => 15000,
    "17" => 18000,
    "18" => 20000,
    "19" => 22000,
    "20" => 25000,
    "21" => 33000,
    "22" => 41000,
    "23" => 50000,
    "24" => 62000,
    "25" => 75000,
    "26" => 90000,
    "27" => 105_000,
    "28" => 120_000,
    "29" => 135_000,
    "30" => 155_000
  }

  @doc "Get the encounter multiplier based on number of monsters."
  def get_multiplier(monster_count) do
    cond do
      monster_count == 1 -> 1.0
      monster_count == 2 -> 1.5
      monster_count in 3..6 -> 2.0
      monster_count in 7..10 -> 2.5
      monster_count in 11..14 -> 3.0
      true -> 4.0
    end
  end

  @doc "Normalize CR string for lookup."
  def parse_cr(cr_str) do
    cr_str = cr_str |> String.trim() |> String.downcase()

    cond do
      String.contains?(cr_str, "/") ->
        cr_str

      String.contains?(cr_str, ".") ->
        case Float.parse(cr_str) do
          {0.125, _} -> "1/8"
          {0.25, _} -> "1/4"
          {0.5, _} -> "1/2"
          _ -> cr_str
        end

      true ->
        cr_str
    end
  end

  @doc """
  Parse monster arguments in format 'count:CR' or 'CR' (assumes count=1).
  Examples: '2:1', '1/4', '3:1/2', '5'
  """
  def parse_monsters(monster_args) do
    Enum.map(monster_args, fn arg ->
      {count, cr_str} = parse_monster_arg(arg)
      cr = parse_cr(cr_str)

      unless Map.has_key?(@cr_xp, cr) do
        IO.puts(:stderr, "Error: Unknown CR '#{cr_str}'")
        System.halt(1)
      end

      {count, cr}
    end)
  end

  # TODO: Probably I can merge this with parse_count_value. I just need to consider the CR string case.
  defp parse_monster_arg(arg) do
    case String.split(arg, ":", parts: 2) do
      [count, cr] -> {String.to_integer(count), cr}
      [cr] -> {1, cr}
    end
  end

  @doc """
  Parse party arguments in format 'count:level' or 'level' (assumes count=1).
  Examples: '2:5', '3', '1:10'
  """
  def parse_party(party_args) do
    Enum.flat_map(party_args, fn arg ->
      {count, level} = parse_count_value(arg)

      if level < 1 or level > 20 do
        IO.puts(:stderr, "Error: Invalid level #{level}. Must be 1-20.")
        System.halt(1)
      end

      List.duplicate(level, count)
    end)
  end

  defp parse_count_value(arg) do
    case String.split(arg, ":", parts: 2) do
      [count, value] ->
        {String.to_integer(count), String.to_integer(value)}

      [value] ->
        {1, String.to_integer(value)}
    end
  end

  @doc "Calculate total party thresholds for each difficulty."
  def calculate_party_thresholds(party) do
    Enum.reduce(party, {0, 0, 0, 0}, fn level, {easy, medium, hard, deadly} ->
      {e, m, h, d} = @xp_thresholds[level]
      {easy + e, medium + m, hard + h, deadly + d}
    end)
  end

  @doc "Calculate encounter difficulty and XP."
  def calculate_encounter(monsters, party) do
    {total_monster_count, base_xp} =
      Enum.reduce(monsters, {0, 0}, fn {count, cr}, {tc, xp} ->
        {tc + count, xp + count * @cr_xp[cr]}
      end)

    multiplier = get_multiplier(total_monster_count)
    adjusted_xp = trunc(base_xp * multiplier)

    {easy, medium, hard, deadly} = calculate_party_thresholds(party)

    difficulty =
      cond do
        adjusted_xp >= deadly -> "Deadly"
        adjusted_xp >= hard -> "Hard"
        adjusted_xp >= medium -> "Medium"
        adjusted_xp >= easy -> "Easy"
        true -> "Trivial"
      end

    xp_per_character = div(base_xp, length(party))

    %{
      difficulty: difficulty,
      base_xp: base_xp,
      adjusted_xp: adjusted_xp,
      multiplier: multiplier,
      xp_per_character: xp_per_character,
      monster_count: total_monster_count,
      party_size: length(party),
      thresholds: %{
        easy: easy,
        medium: medium,
        hard: hard,
        deadly: deadly
      }
    }
  end

  def format_number(n) do
    n
    |> Integer.to_string()
    |> String.reverse()
    |> String.to_charlist()
    |> Enum.chunk_every(3)
    |> Enum.join(",")
    |> String.reverse()
  end

  def print_usage do
    IO.puts("""
    D&D 5e Encounter Difficulty Calculator

    Usage: elixir encounter_difficulty.exs -m MONSTERS -p PARTY

    Options:
      -m, --monsters  Monsters in format 'count:CR' or just 'CR'. Examples: 2:1, 1/4, 3:1/2
      -p, --party     Party members in format 'count:level' or just 'level'. Examples: 2:5, 3, 1:10
      -h, --help      Show this help message

    Examples:
      elixir encounter_difficulty.exs -m 2:1 1:2 -p 2:2 1:3
        2 CR 1 monsters and 1 CR 2 monster vs 2 level 2 and 1 level 3 characters

      elixir encounter_difficulty.exs -m 1/4 1/4 1/2 -p 4:1
        2 CR 1/4 and 1 CR 1/2 monster vs 4 level 1 characters

      elixir encounter_difficulty.exs --monsters 3:5 --party 4:10
        3 CR 5 monsters vs 4 level 10 characters
    """)
  end

  def parse_args(args) do
    case parse_args(args, %{monsters: [], party: [], current: nil}) do
      :help ->
        :help

      %{monsters: monsters, party: party} = acc ->
        %{acc | monsters: monsters, party: party}
    end
  end

  defp parse_args([], acc), do: acc

  defp parse_args(["-h" | _], _acc), do: :help
  defp parse_args(["--help" | _], _acc), do: :help

  defp parse_args(["-m" | rest], acc), do: parse_args(rest, %{acc | current: :monsters})
  defp parse_args(["--monsters" | rest], acc), do: parse_args(rest, %{acc | current: :monsters})

  defp parse_args(["-p" | rest], acc), do: parse_args(rest, %{acc | current: :party})
  defp parse_args(["--party" | rest], acc), do: parse_args(rest, %{acc | current: :party})

  defp parse_args([arg | rest], acc) do
    case acc.current do
      :monsters ->
        parse_args(rest, %{acc | monsters: [arg | acc.monsters]})

      :party ->
        parse_args(rest, %{acc | party: [arg | acc.party]})

      nil ->
        IO.puts(:stderr, "Error: Unexpected argument '#{arg}'")
        System.halt(1)
    end
  end

  def main(args) do
    case parse_args(args) do
      :help ->
        print_usage()

      %{monsters: [], party: _} ->
        IO.puts(:stderr, "Error: --monsters is required")
        print_usage()
        System.halt(1)

      %{monsters: _, party: []} ->
        IO.puts(:stderr, "Error: --party is required")
        print_usage()
        System.halt(1)

      %{monsters: monster_args, party: party_args} ->
        monsters = parse_monsters(monster_args)
        party = parse_party(party_args)
        result = calculate_encounter(monsters, party)

        IO.puts("")
        IO.puts(String.duplicate("=", 50))
        IO.puts("        D&D 5e ENCOUNTER DIFFICULTY")
        IO.puts(String.duplicate("=", 50))

        IO.puts("\nParty: #{result.party_size} characters")
        IO.puts("Monsters: #{result.monster_count} (x#{result.multiplier} multiplier)")

        IO.puts("\n--- Party XP Thresholds ---")
        IO.puts("  Easy:   #{format_number(result.thresholds.easy)} XP")
        IO.puts("  Medium: #{format_number(result.thresholds.medium)} XP")
        IO.puts("  Hard:   #{format_number(result.thresholds.hard)} XP")
        IO.puts("  Deadly: #{format_number(result.thresholds.deadly)} XP")

        IO.puts("\n--- Encounter ---")
        IO.puts("  Base XP:     #{format_number(result.base_xp)} XP")
        IO.puts("  Adjusted XP: #{format_number(result.adjusted_xp)} XP (for difficulty)")

        IO.puts("\n" <> String.duplicate("=", 50))
        IO.puts("  DIFFICULTY: #{String.upcase(result.difficulty)}")
        IO.puts(String.duplicate("=", 50))

        IO.puts("\n  Total XP Award:      #{format_number(result.base_xp)} XP")
        IO.puts("  XP per Character:    #{format_number(result.xp_per_character)} XP")
        IO.puts("")
    end
  end
end

EncounterDifficulty.main(System.argv())

Let’s be clear: I love Racket. It’s just that there’s always a reason to prefer another language if the project will involve anyone other than me. ↩︎

Any news from Clojure front?

Most Promising Programming Languages of 2017

My view on Elixir and Clojure