Interactive fiction engine which runs as a Gemini server
chore: upgrade linters and fix linting issues
Update infrastructure dependencies
build: Install go1.16 directly rather than upgrading


browse  log 
release notes 



You can also use your local clone with git send-email.


builds.sr.ht status

GemIF is a simple Interactive Fiction engine which runs as a Gemini server.

Check out my live GemIF instance with your favorite gemini client at gemini://gemif.fedi.farm or through a gemini web portal like the one at portal.mozz.us. Though be warned the web portal does terrible things to the ASCII art.



Compiled binaries for several architectures are automatically generated on each tagged commit. You can find the latest one and download it

You can also do a good old-fashioned go get:

  • go get git.sr.ht/~nromdotcom/gemif/cmd/gemif to get the server
  • go get git.sr.ht/~nromdotcom/gemif/cmd/gemifc to get the story compiler

Otherwise, you can clone this repo and use the regular golang toolchain to build (check the Makefile for details).


Once you have the binary compiled, you need a few files to make it run.

#Step One: Generate your TLS Cert

The first thing to do is generate your TLS cert in whatever way makes sense for you.

In production, you might use certbot in standalone mode to generate a LetsEncrypt cert.

Otherwise, since most (all?) Gemini clients use TOFU for TLS certificates, you can also feel free to generate a self-signed cert in whatever way is appropriate for you.

#Step Two: Gather up your stories

This repo comes with a couple of sample stories in ./stories (also bundled as artifacts alongside the binaries in the releases linked above). If you want to add, remove, or change them, go ahead and do that now (see below for details on writing your own).

#Step Three: Make a config file

GemIF configures itself based on the contents of ./config.toml. Take sample.config.toml and copy it. Change the configuration to match your desired values.

#Run it

That's it. Go ahead and run the binary.

$ ./bin/gemif-linux-amd64/gemif
Starting GemIF 0.1.1 (bd561ac) - built 2020.12.05.210341

[gig-debug] ⇨ gemini server started on [::]:1965
time="2020-12-05T21:29:40-05:00" path=/ status=20 duration=0.28

#Writing Stories

GemIF loads stories from YAML files (from the directory named in engine.stories_dir in config.toml), but authors have the option to write their stories in GemIF format using .gemif files.

#.gemif files and gemifc

GemIF comes with a story called "Writing Tutorial" which provides guided documentation on writing GemIF stories.

You can see the live story at gemini://gemif.fedi.farm/game/Cgh0dXRvcmlhbBIKdGhlX2Jhc2ljcw== or the source of the story right in this repo at stories/src/tutorial.


MIT © Norm MacLennan