Updates to the plugin documentation.

Author: GraylinKim

docs/source/articles/creatingagameengineplugin.rst

@@ -33,7 +33,10 @@ Given the following plugins::
         def handleTargetAbilityEvent(self, event, replay):
             pass
 
-An engine handling a ``TargetAbilityEvent`` would call handlers in the following order::
+    sc2reader.engine.register_plugin(Plugin1())
+    sc2reader.engine.register_plugin(Plugin2())
+
+When the engine handles a ``TargetAbilityEvent`` it will call handlers in the following order::
 
     Plugin1.handleAbilityEvent(event, replay)
     Plugin2.handleEvent(event, replay)
@@ -84,3 +87,12 @@ If a plugin wishes to stop processing a replay it can yield a PluginExit event b
 The GameEngine will intercept this event and remove the plugin from the list of active plugins for this replay. The exit code and details will be available from the replay::
 
 	code, details = replay.plugins['MyPlugin']
+
+Using Your Plugin
+-----------------
+
+To use your plugin with sc2reader, just register it to the game engine:
+
+	sc2reader.engine.register_plugin(MyPlugin())
+
+Plugins will be called in order of registration for each event. If plugin B depends on plugin A make sure to register plugin A first!

docs/source/plugins.rst

@@ -1,26 +1,42 @@
 Plugins
 =============
 
-A plugin is pretty much just a callable function or object that accepts a replay
-file as a single argument. sc2reader supports assignment of plugins to different
-resource types via the :meth:`SC2Factory.register_plugin` factory method.
+sc2reader has a built in game engine that you can plug into to efficiently process replay events. You can add plugins to the engine by calling :meth:`~sc2reader.engine.engine.GameEngine.register_plugin`::
 
-::
+	import sc2reader
+	from sc2reader.engine.plugins import APMTracker, SelectionTracker
+	sc2reader.engine.register_plugin(APMTracker())
+	sc2reader.engine.register_plugin(SelectionTracker())
 
-    import sc2reader
-    from sc2reader.plugins.replay import APMTracker, SelectionTracker
-    sc2reader.register_plugin('Replay',APMTracker())
-    sc2reader.register_plugin('Replay',SelectionTracker())
+Plugins will be called in order of registration for each event. If plugin B depends on plugin A make sure to register plugin A first!
 
-The order you register plugins is the order they are executed in so be careful to
-put register in the right order if you have dependencies between plugins.
+See the :doc:`articles/creatingagameengineplugin` article for instructions on making your own plugins.
+
+
+ContextLoader
+-------------
+
+.. note::
+
+	This plugin is registered by default.
+
+This plugin creates and maintains all the :class:`~sc2reader.data.Unit` and :class:`~sc2reader.data.Ability` data objects from the raw replay data. This creates all the ``event.player``, ``event.unit``, ``event.ability`` object references and maintains other game data structures like :attr:`~sc2reader.resources.Replay.objects`.
+
+
+GameHeartNormalizer
+---------------------
+
+.. note::
+
+	This plugin is registered by default.
+
+This plugin fixes player lists, teams, game lengths, and frames for games that were played with the GameHeart mod.
 
 
 APMTracker
 ----------------
 
-The APMTracker adds three simple fields based on a straight tally of non-camera
-player action events such as selections, abilities, and hotkeys.
+The :class:`~sc2reader.engine.plugins.APMTracker` adds three simple fields based on a straight tally of non-camera player action events such as selections, abilities, and hotkeys.
 
 * ``player.aps`` = a dictionary of second => total actions in that second
 * ``player.apm`` = a dictionary of minute => total actions in that minute
@@ -30,21 +46,12 @@ player action events such as selections, abilities, and hotkeys.
 SelectionTracker
 --------------------
 
-The :class:`SelectionTracker` plugin simulates every person's selection at every
-frame in both the hotkey and active selection buffers. This selection information
-is stored in ``person.selection`` as a two dimensional array of lists.
-
-::
-
-    unit_list = replay.player[1].selection[frame][buffer]
+.. note::
 
-Where buffer is a control group 0-9 or 10 which represents the active selection.
+	This plugin is intended to be used in conjunction with other user written plugins. If you attempt to use the ``player.selection`` attribute outside of a registered plugin the values will be the values as they were at the end of the game.
 
-Keep in mind that the buffers are only updated for the following events:
+The :class:`SelectionTracker` maintains a ``person.selection`` structure maps selection buffers for that player to the player's current selection::
 
- * The active selection changes
- * When unit types change (eggs hatch, tanks siege)
+    active_selection = event.player.selection[10]
 
-Buffers are not updated when units die unless the unit dies while selected (because
-the active selection must change). Units that die while deslected won't get deselected
-until the next time the control group they were saved in becomes active.
+Where buffer is a control group 0-9 or a 10 which represents the active selection.