# HG changeset patch # User Steve Losh # Date 1312951048 14400 # Node ID 2e42d7f29dde1843788e390c8588b50ef5186659 # Parent 99b79096ff32d1c11d2b96ed80b16748a862352c Moar docs. diff -r 99b79096ff32 -r 2e42d7f29dde docs.markdown --- a/docs.markdown Wed Aug 10 00:24:05 2011 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,87 +0,0 @@ -Basics -====== - -When you connect to a server you get a `Bot` object back. You can connect with -`(clojurecraft.core/connect {:name "hostname" :port INT})`. - -Once you've got a bot you can query it for data about its world and tell it to -perform actions. - -Transactions -============ - -There are two main types of data you'll want to observe with your bots: chunks and -entities. A `World` object contains two maps: one of entities and one of chunks. - -Each of these maps is a ref, and each of the entries in each map is also a ref. This -may seem excessive -- why not simply make each map a ref *or* each entry a ref? - -### Top-Level Refs - -The maps themselves clearly need to be refs so that multiple bots sharing the same -world can update them safely. - -### Entry Refs - -To understand the reason for making each entity a ref consider a bot with the -following goal: - -"Find all the hostile mobs. Pick the one with the lowest health and attack it." - -Now imagine that during the process of picking a mob to kill the bot received an -update about one of the peaceful entities. - -If the entries of the map were not themselves refs the bot would *have* to -synchronize on the entire map. This peaceful entity update would cause a retry of -the transaction even though the bot doesn't care about peaceful entities at all! - -Making each entity its own ref means we can do the following: - -* Inside of a dosync: - * Find all the hostile mobs. - * `ensure` on all of them. - * Perform our calculations. - -This lets us ignore updates to peaceful mobs, but retry when a hostile mob is updated -(perhaps someone else has killed one). Keeping the "find mobs" step inside the -dosync ensures that if a mob despawns we will be looking at an accurate list the next -time we retry. - -Note that if a new hostile mob is spawned it will not cause a retry. If you are -performing an action that needs perfectly accurate data you can always synchronize -on the maps themselves, but be aware that this will probably not be very performant. - -### Entity Despawns - -This also reveals the reason for the `:despawned` entry in an `Entity` object: if we -simply removed the entity from the map when it despawned any transactions depending -on that entity wouldn't be restarted. Setting the `:despawned` value on an entity -modifies it and triggers appropriate retries. - -Actions -======= - -Actions are functions that take a `Bot` object and some arguments and handle writing -the packets to make the bot perform the action. - -### move - -`(clojurecraft.actions/move bot x y z)` - -The `move` action adjusts the location of the bot. This lets it move around the -world. - -Right now you can't really use the `y` argument. Use `clojurecraft.actions/jump` -instead. - -This action is fairly low level. Expect to see some fun path-finding -algorithms/libraries in the future that will remove the need to call this directly. - -### jump - -`(clojurecraft.actions/jump bot)` - -Tells the bot to jump, if possible. - -Events -====== diff -r 99b79096ff32 -r 2e42d7f29dde docs/source/actions.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/source/actions.rst Wed Aug 10 00:37:28 2011 -0400 @@ -0,0 +1,26 @@ +Actions +======= + +Actions are functions that take a ``Bot`` object and some arguments and handle +writing the packets to make the bot perform the action. + +jump +---- + +``(clojurecraft.actions/jump bot)`` + +Tells the bot to jump, if possible. + +move +---- + +``(clojurecraft.actions/move bot x y z)`` + +The ``move`` action adjusts the location of the bot. This lets it move around the +world. + +Right now you can't really use the ``y`` argument. Use ``clojurecraft.actions/jump`` +instead. + +This action is fairly low level. Expect to see some fun path-finding +algorithms/libraries in the future that will remove the need to call this directly. diff -r 99b79096ff32 -r 2e42d7f29dde docs/source/basics.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/source/basics.rst Wed Aug 10 00:37:28 2011 -0400 @@ -0,0 +1,10 @@ +Basic Concepts +============== + +When you connect to a server you get a ``Bot`` object back. You can connect with +``(clojurecraft.core/connect {:name "hostname" :port INT} "username")``. + +Once you've got a bot you can query it for data about its world and tell it to +perform actions. + + diff -r 99b79096ff32 -r 2e42d7f29dde docs/source/events.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/source/events.rst Wed Aug 10 00:37:28 2011 -0400 @@ -0,0 +1,2 @@ +Events +====== diff -r 99b79096ff32 -r 2e42d7f29dde docs/source/index.rst --- a/docs/source/index.rst Wed Aug 10 00:24:05 2011 -0400 +++ b/docs/source/index.rst Wed Aug 10 00:37:28 2011 -0400 @@ -15,7 +15,11 @@ :maxdepth: 2 quickstart + basics datastructures + transactions + actions + events Indices and tables diff -r 99b79096ff32 -r 2e42d7f29dde docs/source/transactions.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/source/transactions.rst Wed Aug 10 00:37:28 2011 -0400 @@ -0,0 +1,55 @@ +Transactions +============ + +There are two main types of data you'll want to observe with your bots: chunks and +entities. A ``World`` object contains two maps: one of entities and one of chunks. + +Each of these maps is a ref, and each of the entries in each map is also a ref. This +may seem excessive -- why not simply make each map a ref *or* each entry a ref? + +Top-Level Refs +-------------- + +The maps themselves clearly need to be refs so that multiple bots sharing the same +world can update them safely. + +Entry Refs +---------- + +To understand the reason for making each entity a ref consider a bot with the +following goal: + +"Find all the hostile mobs. Pick the one with the lowest health and attack it." + +Now imagine that during the process of picking a mob to kill the bot received an +update about one of the peaceful entities. + +If the entries of the map were not themselves refs the bot would *have* to +synchronize on the entire map. This peaceful entity update would cause a retry of +the transaction even though the bot doesn't care about peaceful entities at all! + +Making each entity its own ref means we can do the following: + +* Inside of a dosync: + * Find all the hostile mobs. + * ``ensure`` on all of them. + * Perform our calculations. + +This lets us ignore updates to peaceful mobs, but retry when a hostile mob is updated +(perhaps someone else has killed one). Keeping the "find mobs" step inside the +dosync ensures that if a mob despawns we will be looking at an accurate list the next +time we retry. + +Note that if a new hostile mob is spawned it will not cause a retry. If you are +performing an action that needs perfectly accurate data you can always synchronize +on the maps themselves, but be aware that this will probably not be very performant. + +Entity Despawns +--------------- + +This also reveals the reason for the ``:despawned`` entry in an ``Entity`` object: if +we simply removed the entity from the map when it despawned any transactions +depending on that entity wouldn't be restarted. Setting the ``:despawned`` value on +an entity modifies it and triggers appropriate retries. + +