From 644b87a848e7d5595c22a6294b0e940b80c9c55e Mon Sep 17 00:00:00 2001 From: Grant Shangreaux Date: Sat, 12 Feb 2022 21:56:09 -0600 Subject: [WIP] Docs: fill out tutorial nature of the document cover Emacs, Lisp, and org mode gently as we go along --- wink-murder.org | 82 ++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 70 insertions(+), 12 deletions(-) diff --git a/wink-murder.org b/wink-murder.org index 8b84e7f..e5c3230 100644 --- a/wink-murder.org +++ b/wink-murder.org @@ -1,19 +1,63 @@ -* Building a Murder Mystery Game Prototype +* Building a Murder Mystery Sim Prototype With Emacs ** Summary -ideally a small city/village simulator where there are many independent actors -all doing their routines. one of them gets triggered by something and commits -a murder. they will continue to murder any time their pattern is triggered until -the player figures out who they are. + +This document serves as a tutorial for Emacs, Lisp, and org-mode's literate +programming features. It provides a way to distribute the notes, code, and +execution environment all in one place. Anyone reading this document can also +edit and execute the code in it. This is the beauty of literate programs, where +the program is written for humans as prose with embedded code. + +Ideally I would like to create a small city/village simulator where there +are many independent actors all doing their routines. One of the actors gets +triggered by something and commits a murder. Then the player acts as detective, +talking to other actors and gaining clues to solve who-done-it. ** Wink Murder - boiling it down -the game [[https://en.wikipedia.org/wiki/Wink_murder]["Wink Murder"]] is -a very simplified version of this, and serves as a starting point to work -out a prototype. for fun, i'm just doing this in emacs-lisp. the following -source block represents the whole program from a high level: +The game [[https://en.wikipedia.org/wiki/Wink_murder]["Wink Murder"]] is +a simplified murder mystery and serves as a starting point to work out +a prototype. Actors observe one another while the killer tries to wink at +any innocent they make eye contact with before being accused and caught. This +will be a pure simulation, where we can learn about creating actor behavior +representing knowledge. + +Does the killer think they're being watched? + +Did one of the innocents notice them wink? + +How can we encode some of these behaviors into a simulated version of people +sitting in a circle and playing this game? + +** Org mode + +If you're reading this in Emacs, you probably see headings with different colors +depending on their level. These headings can be folded by pressing TAB when the +cursor is on them. Navigation by heading is also possible, but we won't worry about +it for now. Notice in the section above, "Wink Murder" looks like a link. Click +it. Depending on what you have installed, you should land in a browser at the +Wikipedia page for the game. If you really like Emacs, you can even use ~eww~ as +the default browser to open links in. Keep an eye out for links in this program. +They can be links to nearly anything, like [[info:org#Top][this link to the org-mode info manual]]. + +I will ask you to learn just *two* keyboard shortcuts. Meta-x and Ctrl-c Ctrl-c. +(written ~M-x~ and ~C-c C-c~ after this). Meta will be your alt key or possibly +option, it depends on your machine and OS. ~M-x~ is for ~execute-extended-command~ +which lets you run /any/ command avaliable in Emacs. Combined with a good +completion engine, it offers one way to discover what things are possible. +~C-c C-c~ does many things depending on context, in this case, specific to +~org-mode~. Mostly, you will use it to execute blocks of code in this program. * Program Overview +The following source block represents the whole program from a high level. +its like a table of contents, where each of the ~<>~ blocks actually +points to other source code blocks in this document. The header argument +~:noweb yes~ tells ~org-mode~ to unfold the references into code, so when +it sees ~<>~, it will insert the code from the block with +that name. The header argument ~:tangle yes~ means we can evaluate +~(org-babel-tangle)~ and it will unfold all of the code references into +a source file. This is the core of literate programming. + #+name: wink-murder #+begin_src emacs-lisp :noweb yes :tangle yes :results silent ;;; wink-murder.el --- Emacs Wink-Murder game simulation -*- lexical-binding:t -*- @@ -33,16 +77,30 @@ source block represents the whole program from a high level: <> #+end_src -If you put your cursor on the block above and press C-c C-c, Emacs will +** Working with source blocks + +If you put your cursor on the block above and press ~C-c C-c~, Emacs will ask if you want to evaluate the code on your system. This is a good thing, since you are executing most of the elisp in this file without looking at it! You can set a variable to allow it to execute automatically, but -its nice to have the safety on. +its nice to have the safety on. You can turn it off with ~C-c C-c~ on the +block below: #+begin_src emacs-lisp -(setq org-confirm-babel-evaluate nil) + (setq org-confirm-babel-evaluate nil) #+end_src +** A little bit of Lisp + +What does that expression up there do? Its basically the equivalent to +~variable = value~ in Ruby or other languages. In Lisp, everything is an +expression, symbols are important, and lists are surrounded with parens. +When we evaluate Lisp, HERE-IS-WHERE-I-LEFT-OFF + +~setq~ actually stands +for "set quote". ~quote~ is a special form in Lisp that says "don't evaluate +the next expression, just return it". Var + Now you should be able to press M-x wink-murder-play and it will prompt you for a number of players. Enter 4 (lower) will. Then look at the *Messages* buffer, you can either find it through the menu bar, ~M-x switch-to-buffer~ -- cgit v1.2.3