# HG changeset patch # User Steve Losh # Date 1314397534 14400 # Node ID d65fe7dddf1f0c20e0c44438c8584e71524977d0 # Parent a587910b3c7d88396ac627b4901ef010c193da35 More documentation. diff -r a587910b3c7d -r d65fe7dddf1f docs/source/actions.rst --- 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)`` diff -r a587910b3c7d -r d65fe7dddf1f docs/source/events.rst --- 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. diff -r a587910b3c7d -r d65fe7dddf1f docs/source/index.rst --- 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 diff -r a587910b3c7d -r d65fe7dddf1f docs/source/loops.rst --- /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) diff -r a587910b3c7d -r d65fe7dddf1f src/clojurecraft/data.clj --- 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