29631ac2b821

More docs.
[view raw] [browse files]
author Steve Losh <steve@stevelosh.com>
date Wed, 10 Aug 2011 01:48:55 -0400
parents 43f02bd6b197
children 0ae169e20952
branches/tags (none)
files docs/source/events.rst docs/source/quickstart.rst

Changes

diff -r 43f02bd6b197 -r 29631ac2b821 docs/source/events.rst
--- a/docs/source/events.rst	Wed Aug 10 01:25:24 2011 -0400
+++ b/docs/source/events.rst	Wed Aug 10 01:48:55 2011 -0400
@@ -1,2 +1,42 @@
 Events
 ======
+
+The main way you'll interact with your Clojurecraft bots is through event handlers.
+
+Event handlers are functions you create that respond to events that happen in the
+Minecraft world.  They return a list of Actions that you want your bot to perform.
+
+Event handlers are pure functions that should take the bot as their first argument.
+Their other arguments will depend on the particular handler.
+
+Creating and Registering Event Handlers
+---------------------------------------
+
+The first thing you need to do is create an event handling function::
+
+    (defn jump-on-chat [bot message]
+      [(clojurecraft.actions/jump bot)])
+
+Then register the handler for the action::
+
+    (clojurecraft.events/add-handler bot :chat `jump-on-chat)
+
+Notice that you don't pass the function directly to the ``add-handler`` function.
+You pass a syntax quoted symbol to the function.  This is an extra character to type,
+but it means you can redefine the function in the REPL and your changes will take
+effect immediately in all of the currently running bots.
+
+Available Events
+----------------
+
+You can register handlers for the following events.
+
+``:chat``
+`````````
+
+::
+
+    (defn chat-handler [message]
+      [... actions ...])
+
+Chat events are fired when a chat message arrives.
diff -r 43f02bd6b197 -r 29631ac2b821 docs/source/quickstart.rst
--- a/docs/source/quickstart.rst	Wed Aug 10 01:25:24 2011 -0400
+++ b/docs/source/quickstart.rst	Wed Aug 10 01:48:55 2011 -0400
@@ -41,7 +41,7 @@
 Once your bot is in the world you're all set to play around.  At the moment the only
 action implemented is basic movement.  Move your bot around with ``act/move``::
 
-    (act/move bot 2 0 1)
+    (force (act/move bot 2 0 1))
 
 The numbers are the x, y, and z distance you wish to move.  For now you can't use the
 ``y`` argument -- you must always pass ``0``.
@@ -52,7 +52,7 @@
 
 Now try jumping::
 
-    (act/jump bot)
+    (force (act/jump bot))
 
 Clojurecraft isn't stable and is evolving quickly, but you can check out these docs
 to read about some of the design decisions.  As soon as you see a ``v1.0.0`` tag