f1ef4d543cc010bb97d0d825503ff0ece1841ed7 — Norm MacLennan 2 years ago 9469147
README updates for new features
1 files changed, 70 insertions(+), 5 deletions(-)

M README.md => README.md +70 -5
@@ 1,5 1,7 @@
# GemIF

[![builds.sr.ht status](https://builds.sr.ht/~nromdotcom/gemif.svg)](https://builds.sr.ht/~nromdotcom/gemif?)

GemIF is a simple [Interactive Fiction](https://en.wikipedia.org/wiki/Interactive_fiction) 
engine which runs as a [Gemini](https://gemini.circumlunar.space/) server.

@@ 51,9 53,69 @@ Each exit contains:
* exit_description: a description of the exit (the text of the exit link)
* destiantion_id: the id of the room this exit takes you to
* exit_id: a unique id for the exit, I recommend a GUID
* set_condition: conditional tag to attach to the game state if the user takes this exit
* if_condition: conditional tag the user must posses to use this exit

### Conditions

Conditions are simple tags attached to the user's state. Condition usage will
vary from story to story, and some will not require conditions at all, but you
might use them to:
* Track something that has (or has not) happened in the story
* Track if a user has (or has not) picked up an object
* Track that the user has said a certain thing to somebody

Conditions are set as part of using exits and can be used to control which
exits a user can use in the future as well as used within room descriptions
to offer conditional passages.

### Description Templates

Speaking of which, room descriptions are rendered as golang `text/template`
templates with the active gamestate in scope. This allows you to perform a
little bit of logic with regards to what you display to the user, how, and

The following struct is in scope within your template:

type GameState struct {
	StoryID     string   `json:"si"`
	CurrentRoom string   `json:"cr"`
	Conditions  []string `json:"cn"`

StoryID and CurrentRoom (RoomID) probably aren't very interesting, but
Conditions can be used to perform conditional rendering.

`GameState` offers some (currently one) convenience function to help
simplify your rendering when it comes to conditions.

The sample in the repo contains a walking tour of my home. But here's
a simpler sample:
`ConditionMet(condition string) bool` can help you quickly tell if a user
meets a specific condition:

- room_id: the_end
  room_name: The End
  room_description: |
    Though because this is a simple demo, you always end up in the same place.

    {{- if .ConditionMet "choice_a"}}

    oh cool, you made choice a! nice work.
    {{- end}}
    {{- if .ConditionMet "choice_b"}}

    oh you made choice b, that's too bad :(
    {{- end}}

### Quick Sample

The sample in the repo contains a walking tour of my home and another
contains some examples of the use of conditions. But here's a simpler


@@ 76,9 138,12 @@ rooms:
Hopefully between these two examples, you can get an idea of how you can build
simple linear or branching stories.

I plan to do a little bit of extension soon to add, like, conditions that determine
which descriptions are printed and which exits are available. But honestly probably
not much beyond that to avoid getting too complex.
I plan to continue to extend the features available to offers to add a little
more flexibility, but part of the idea is that it's meant to be simple so I'm
trying to be careful of how much I add.

Currently focused on refactoring and solidifying the foundation of the
application so it is performant and maintainable.

## License