d65fe7dddf1f

More documentation.
[view raw] [browse files]
author Steve Losh <steve@stevelosh.com>
date Fri, 26 Aug 2011 18:25:34 -0400
parents a587910b3c7d
children cb2d6c82204a
branches/tags (none)
files docs/source/actions.rst docs/source/events.rst docs/source/index.rst docs/source/loops.rst src/clojurecraft/data.clj

Changes

--- 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