--- a/docs/source/actions.rst Fri Aug 26 18:12:13 2011 -0400
+++ b/docs/source/actions.rst Fri Aug 26 18:25:34 2011 -0400
@@ -5,6 +5,9 @@
a delayed function that will handle writing the packets to your bot perform the
action.
+Performing Actions
+------------------
+
If you want to make your bot perform an action immediately you should use ``force``
to make it happen::
@@ -13,8 +16,14 @@
Technically you don't need to use ``force``, because the REPL's printing will force
the result to be evaluated, but conceptually it's a good habit to get into.
+Available Actions
+-----------------
+
+There are a number of actions your bots can perform. More will be added in the
+future.
+
chat
-----
+~~~~
``(clojurecraft.actions/chat bot message)``
@@ -36,14 +45,14 @@
You might also be writing a bot for a modded server that allows longer messages.
jump
-----
+~~~~
``(clojurecraft.actions/jump bot)``
Tells the bot to jump, if possible.
look-to
--------
+~~~~~~~
``(clojurecraft.actions/look-to bot pitch)``
@@ -55,7 +64,7 @@
* ``90``: looking straight down.
look-up
--------
+~~~~~~~
``(clojurecraft.actions/look-up bot)``
@@ -64,7 +73,7 @@
Exactly equivalent to ``(clojurecraft.actions/look-to bot -90.0)``.
look-down
----------
+~~~~~~~~~
``(clojurecraft.actions/look-down bot)``
@@ -73,7 +82,7 @@
Exactly equivalent to ``(clojurecraft.actions/look-to bot 90.0)``.
look-straight
--------------
+~~~~~~~~~~~~~
``(clojurecraft.actions/look-straight bot)``
@@ -82,7 +91,7 @@
Exactly equivalent to ``(clojurecraft.actions/look-to bot 0.0)``.
turn-to
--------
+~~~~~~~
``(clojurecraft.actions/turn-to bot yaw)``
@@ -105,7 +114,7 @@
a certain direction at the moment, but I'll keep looking.
turn-north
-----------
+~~~~~~~~~~
``(clojurecraft.actions/turn-north bot)``
@@ -114,7 +123,7 @@
Exactly equivalent to ``(clojurecraft.actions/turn-to bot 90.0)``.
turn-south
-----------
+~~~~~~~~~~
``(clojurecraft.actions/turn-south bot)``
@@ -123,7 +132,7 @@
Exactly equivalent to ``(clojurecraft.actions/turn-to bot 270.0)``.
turn-east
----------
+~~~~~~~~~
``(clojurecraft.actions/turn-east bot)``
@@ -132,7 +141,7 @@
Exactly equivalent to ``(clojurecraft.actions/turn-to bot 180.0)``.
turn-west
----------
+~~~~~~~~~
``(clojurecraft.actions/turn-west bot)``
@@ -141,7 +150,7 @@
Exactly equivalent to ``(clojurecraft.actions/turn-to bot 0.0)``.
move
-----
+~~~~
``(clojurecraft.actions/move bot x y z)``
@@ -155,7 +164,7 @@
algorithms/libraries in the future that will remove the need to call this directly.
respawn
--------
+~~~~~~~
``(clojurecraft.actions/respawn bot)``
--- a/docs/source/events.rst Fri Aug 26 18:12:13 2011 -0400
+++ b/docs/source/events.rst Fri Aug 26 18:25:34 2011 -0400
@@ -1,7 +1,8 @@
Events
======
-The main way you'll interact with your Clojurecraft bots is through event handlers.
+One of the main ways your Clojurecraft bots will interact with the world 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.
--- a/docs/source/index.rst Fri Aug 26 18:12:13 2011 -0400
+++ b/docs/source/index.rst Fri Aug 26 18:25:34 2011 -0400
@@ -20,6 +20,7 @@
transactions
actions
events
+ loops
Indices and tables
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/source/loops.rst Fri Aug 26 18:25:34 2011 -0400
@@ -0,0 +1,43 @@
+Loops
+=====
+
+Another way your bots will interact with the world is through loops.
+
+Loops are functions that repeatedly run with a delay in between each run. They
+return a list of Actions that you want your bot to perform, just like event handlers.
+
+Loops are pure functions that should take a single argument: the bot.
+
+Adding Loops
+------------
+
+To add a loop to your bot, you first need to create the loop function::
+
+ (defn jump [bot]
+ [(clojurecraft.actions/jump bot)])
+
+Now you can add it to the bot::
+
+ (clojurecraft.loops/add-loop bot #'jump 3000 :jump-loop)
+
+The first argument to the ``add-loop`` function is your bot.
+
+Next is a symbol to your loop function. The reason for passing a symbol is the same
+as the reason you pass a symbol to event handlers.
+
+Next is the number of milliseconds you want to wait in between each run of the loop
+function.
+
+Finally you must pass a "loop ID" keyword. It can be anything you like, but it must
+be unique for each loop added to a given bot. This is what you'll use to remove
+the loop from the bot later.
+
+This example adds a loop to the bot that will make it jump every three seconds.
+
+Removing Loops
+--------------
+
+Removing a loop from a bot is as simple as calling ``remove-loop`` with the bot and
+the loop ID you used when adding the loop::
+
+ (clojurecraft.loops/remove-loop bot :jump-loop)
--- a/src/clojurecraft/data.clj Fri Aug 26 18:12:13 2011 -0400
+++ b/src/clojurecraft/data.clj Fri Aug 26 18:25:34 2011 -0400
@@ -106,6 +106,9 @@
; event-handlers -> (ref {:event-type [handler ...]})
; A ref to a map of event handlers.
;
+; loops -> (ref {loop-id :running ...})
+; A ref to a map of loop-ids -> loop-statuses.
+;
; packet-counts-in -> (atom {:packet-type integer})
; packet-counts-out -> (atom {:packet-type integer})
(defrecord Bot [connection username outqueue actionqueue player world