A variety of elisp functions for implementing a solo roleplaying gamesmaster emulator, for playing a full game within an org-file

Category 2bf3436314 Update 'README.org' 1 week ago
LICENSE a0251cd6ef Initial commit 2 years ago
README.org 2bf3436314 Update 'README.org' 1 week ago
egme.el d8dda69afb Dashboard dice output quickfix (works with no threads) 1 year ago
egme.org 90025ab479 [bugfix] add dice variable intialisation 1 year ago


EmacsGME - Emacs GameMaster Emulator

EmacsGME v0.2


Future updates will be over there


EmacsGME is a GameMaster emulator in the style of MythicGME/CRGE/etc, implemented in emacs-lisp for playing solo-roleplaying games entirely within org-mode (or plain text) documents.

As this is my first real use of emacs-lisp, a lot of it is just me trying out different things in a literate-programming style, with an explanatory document (that is overly commented) that tangles into an emacs-lisp file for easy addition into any emacs-setup.


This will have to be manually added for the time being, this is far from being ready for MELPA - if it ever will be. For now, the simplest way to add this to your install is to clone this repo, and place the following into you emacs config:-

(load-file "/path/to/egme.el")

Be sure to put in the correct path for where your copy of egme.el is saved.

If you are doing any hacking on the main org file, another option is:-

(org-babel-load-file "/path/to/egme.org")

to have it automatically tangled and loaded on startup.


Usage should be easy to gleam by reading the egme.org - I have tried to heavily document each function as I write them, not just in how it works but how I hope to extend in the future.

Output to User

All output is printed into the current buffer, within an org-mode style "GameMaster" block, so that the results can be folded away. On the TODO list is to add proper export styles, so your actual plays can be easily and prettily shown as HTML/PDF/whatever...

org-files are the preferred place to play - headings can help define scenes, game info can be hidden in drawers, and more. If not using org-mode, then org-mode will be enabled in the game buffer whenever output is written.

Dice Roller

    The first main feature is the dice roller, the function "egme-roll-dice". This can either be called with "M-x egme-roll-dice", or by the default keybind of "C-c C-g r". After calling, the user is asked to input a dice roll into the mini-buffer. This is to be input as per any usual RPG dice roll, with a modifier, without spaces. Examples of valid choices are:-
  • 1d20
  • 2D6+3
  • d666
  • 3d10-5
  • This will accept any numbers for the dice type, and will roll dice with that range of numbers. This is only treated differently when using multiple-6 dice (D66,D666,D6666...) - in those cases, it will roll that many 6-sided dice and combine them for each digit of the result. Hit return, and the results will be printed into the current buffer like these examples:-

Rolled:  2d12+8
Result:  20

Rolled:  1d666
Result:  646

This function keeps a history of rolls that have been made previously - if you give it no input, then it will reroll the last dice type, or you can scroll back and forth with the up/down keys.

Yes/No Oracle

This features is the main driver of solo-roleplaying with EmacsGME, the yes/no oracle. This function is named "egme-y-n-oracle", and can be called interactively with "M-x egme-y-n-oracle", or with the default keybind of "C-c C-g q". Once called, it will ask the user what question is being asked. Here you can type a question into the minibuffer, which will be included with any output - this is optional. It will also scan the current line, and if a question is found it will be used as the initial input. Once a question has been set (or given blank input) then the function asks for probability. This is a sliding scale between +4 and -4, with a description ranging from "Near Certain" to "Near Impossible" - this will affect the likelihood of getting a yes or no, for tweaking probabilities on a per-question case.. Options are chosen by typing the modifier, or scrolling between them using left & right on the keyboard. The default option is "0 Even Odds" - just hit enter for a question with unclear probability. An example of this output is:-

   Question:  Is the door locked?
Probability:  Likely
     Answer:  Yes

In some cases, these yes/no answers are extended with answer modifiers or random events...

Answer Modifiers

The answers are further modified - in some cases there will be an extremely response, or a partial response. All the possible responses are:-

  • Yes, and...
  • Yes
  • Yes, but...
  • No, but...
  • No
  • No, and...

An example of that output is:-

   Question:  Does the guard notice me?
Probability:  Even odds
     Answer:  Yes, and...

An "and..." implies the answer goes beyond the basic. So "Yes, and.." is exceptionally positive, and "No, and..." is exceptionally negative. Getting "but..." implies a partial success/failure. So "Yes, but..." is partially positive, and "No, but..." is only partially negative.

Random Events

As time goes by, there is an ever-increasing chance of a random event occurring each time you ask a question. When a random event occurs, it is added to the output of the oracle. A random event consists of the focus (what/who is affected by the event), and the detail (a random Action & Subject word combined). Example of a random event occurring is:-

   Question:  Is the machine switched on?
Probability:  Very Unlikely
     Answer:  No
Random Event!
      Focus:  PC Negative
     Detail:  Divide / Jealousy

The likelihood of an event happening can be set by the user, through the variable egme-random-event-threshold, which can is available through the customize system.

The player is left to interpret what these results mean in the context of their game.

The Focus table is based on the random events from Mythic GME, by Word Mill games. The default Action & Subject lists come from my physical card deck, Solo Sci-Fi Sidekick.

NPC & Thread lists

Details of current major NPCs and story threads are also managed within each game file. The data is stored within org drawers at the end of each file, named :NPCS: and :THREADS: - these remain folded to avoid cluttering up what you see. Even in standard text files, if org-mode is on your system the text in these drawers will be made invisible to you during normal play.

Each list has a function to add a new entry to the list, with a default keybind:-

  • C-c C-g n - egme-add-npc
  • C-C C-g t - egme-add-thread

And there are counterparts to delete from the lists - the same bind but with a final capital letter:-

  • C-c C-g N - egme-delete-npc
  • C-c C-g T - egme-delete-thread

When adding to a list, input is taken from the minibuffer. When deleting, you chose an option in the minibuffer through ido-completing-read.

These tie into the random event system - if a random event concerns a thread, it will select one at random for the event. Or if a random event concerns an NPC, a random one will be shown (with the exception of the "New NPC" event). For example:-

   Question:  Do they spot me approaching?
Probability:  Unlikely
     Answer:  No
Random Event!
      Focus:  NPC positive
        NPC:  Henrethia
     Detail:  Procrastinate / Death

   Question:  Is it heavily guarded?
Probability:  Likely
     Answer:  Yes
Random Event!
      Focus:  Move towards thread
     Thread:  Escape the encampment
     Detail:  Move / Randomness

Interpretation of the detail is still up to the player, but can push the game in new and exciting ways.


With the default keybinds, C-C C-g d opens the dashboard buffer. This extra split buffer sits on the right of the game file by default, and shows the current contents of the NPC & thread lists. It will automatically refresh when NPCs/threads are added or deleted, so it can be a handy resource.

This will show more info in the future - current ideas include the current eGME keybinds, last roll results, and more...

More Details

The entire system is developed from a pen & paper system based on actual dice rolls, details of this system can be found within the egme.org file against each function.


  • v0.2 - Added list handling and dashboard for basic game-state display
  • v0.1 - Initial release


The following items are currently on the TODO list - I am open to further suggestions of how this can be improved.

  • Show keybinds in dashboard
  • [DONE] Rework dashboard function, so that it toggles the info buffer Added a toggle function and bound that key
  • More game-state info in the dashboard? Dice rolls DONE
  • [DONE] Add user customization for random event occurrences
  • Add random events for new NPC/thread, which also prompts user to update the list
  • Add a random image oracle for extra inspiration (from a user-specified directory)
  • Convert to a true minor mode, dependent on org
  • Function to "initialise" a game file - set title/description/lists/properties - and styling info for the GameMaster block for exporting
  • Update this README to better reflect the reality of usage (the Sisyphean task)


EmacsGME is licensed under the GPLv2, see included LICENSE file for details.