oracle

What is this?

oracle is a collection of small random text generators I made primarily for use with the Espanso autocompletion tool and for playing solo tabletop games. I’ve decided to share the code of this program on Github in the hopes that someone else will also find it useful. Each module can be installed as it’s own standalone executable. The rest of this readme explains how to use each module of the program.

Have fun!

Installing

To install oracle or it’s submodules either download the binaries from the release page or, if you have Odin installed, simply use the odin build command or the provided build scripts.

git clone https://github.com/via-dev/oracle
cd oracle
odin build . -o:speed

solo: tools for solo tabletop

odin build solo -o:speed

The solo module contains subcommands that act as play-aids to digital solo tabletop gaming. The current commands are:

• dice: a basic dice roller. Cannot (yet) do math, roll non-standard dice or do special functions such as exploding or keeping.

• motif: emulator for the the Motif SRD engine.

• table: setup your own lua files with random tables and roll on them.

• yesno: emulator for the Recluse yes or no oracle for binary answers.

In order to use the table command you must setup your own lua table files in the following locations:

• Windows: %USERPROFILE%\AppData\Local\oracle\tables

• Linux: ~/.config/oracle/tables

Your lua files must contain at least one global function called main. You can then run tables <filename> to execute the code contained in the main function of that file. You can add more functions to your file and call them with tables <filename>:<function>. Below is an example of what a lua file might look like.

local combat = {}

-- Simple d6 table.
combat.twist = {
	"Reinforce",
	"Change",
	"Disadvantage enemy",
	"Advantage self",
	"Bargain",
	"Trick",
}

-- Weighted 3d6 table.
combat.tactic = {}
combat.tactic[3] = "Panic"
combat.tactic[4] = "Surrender"
combat.tactic[5] = "Disengage"
combat.tactic[6] = "Retreat"
combat.tactic[7] = "Guard"
combat.tactic[8] = "Probe"
combat.tactic[9] = "Wear down"
combat.tactic[10] = "Standoff"
combat.tactic[11] = "Balance"
combat.tactic[12] = "Feint"
combat.tactic[13] = "Reverse"
combat.tactic[14] = "Taunt"
combat.tactic[15] = "Press"
combat.tactic[16] = "Strike"
combat.tactic[17] = "Charge"
combat.tactic[18] = "Frenzy"

function main()
-- Common dice functions are available
	local twi = d6(1)
	local tac = d6(3)
	local new = d6(1)

	local newtac = {
		"Same Tactic",
		"Same Tactic",
		"Same Tactic",
		"New Tactic: " .. combat.tactic[tac],
		"New Tactic: " .. combat.tactic[tac],
		"Twist: " .. combat.twist[twi],
	}

-- You must print your results to stdout
	print(newtac[new])
end

function twist()
	local twi = d6(1)
	print(combat.twist[twi])
end

function tactic()
	local tac = d6(3)
	print(combat.tactic[tac])
end

To make rolling on tables easier I’ve made a few functions for rolling common RPG dice available to all files. They take only one argument which is the number of dice to be rolled. These are: d3(), d4(), d6(), d8(), d10(), d12(), d20(), d100() and dF().

For a guide on how to write Lua code, please read the Programming in Lua guide.

iching: use the I Ching for divination

odin build iching -o:speed

The iching module acts as a CLI tool for generating I Ching hexagrams. It generates a basic primary and secondary hexagram reading with yarrow stalk probabilities by default when no arguments are passed. You can pass an optional hexcode argument with the exact hexagram line numbers if you’d like to generate the hexagrams yourself (878899, 777688, 966988, etc).

You can generate additional hexagrams with the following optional flags:

• -e, --extended: generates a reversed hexagram and an anti-hexagram.

• -a, --ascending: generates five ascending hexagrams in between the primary and secondary hexagrams.

The -m or --method flag allows you to choose which method of casting this primary hexagram will be used.

• yarrow: use yarrow stalk probabilities. The default option.

• coins: use three coins probabilities.

• oneline: get hexagrams with a single moving line.

The -t or --translation flag allows you to choose which translation to use for hexagram information. A translation file is a JSON, JSON5 or MJSON file with a .trans extension that contains a table with all the information text for each hexagram.

The program will look for translation files in these locations:

• Windows: %USERPROFILE%\AppData\Local\oracle\iching

• Linux: ~/.config/oracle/iching

Your translation file should follow this format:

// Using MJSON syntax

author = "Takashima Ekidan"

// Write trigram names in this order
trigrams = {
  heaven = "Ken:  Heaven"
  earth = "Kon: Earth"
  lake = "Da: Pond"
  water = "Kan: Water"
  mountain = "Gon: Mountain"
  fire = "Ri: Fire"
  wind = "Son: Wind"
  thunder = "Shin: Thunder"
}

// Array of 64 hexagrams in order
hexagrams = [
  {
    name = "I.  KEN  (Heaven)"
    judgement = "Ken is what is perfect, auspicious, useful, and constant."
    lines = [
      "Positive I.  Represents the obscure dragon lying hidden.  Better not move."
      "Positive II.  The dragon appearing in the field; advantageous to see great men."
      "Positive III.  Honourable men employ themselves assiduously all day long, and are wide awake from morning to evening.  Though dangerous, yet free from blame."
      "Positive IV.  The dragon is as if he were leaping, but in the deep.  Free from blame."
      "Positive V.  The dragon has flown up into the heaven.  Advantageous to see great men."
      "Positive VI.  The dragon is in a state of excesses; and is beset with remorse."
      "The Mode of Using the Positives.  Lucky, if all the dragons are so humble as if they had no heads."
    ]
  },
// Copy the above format for the remaining 63 hexagrams

NOTE:

• You must fill out the data for all 64 hexagrams or the program will complain at you.

• You must follow the King Wen order in your translation file or the wrong information about the wrong hexagrams will be displayed.

geomancy: use Geomancy for divination

odin build geomancy -o:speed

Similar to the above module the geomancy module is a CLI frontend for geomancy divination in the terminal. It will generate a random Shield Chart when no arguments are passed.

It can take four optional arguments for each of the Four Mothers and each one must formatted as four bit binary numbers (1101, 1001, 1111, etc).