seh 0.1.0 → 0.3.0

data/.gitignore

@@ -1,6 +1,5 @@
 *.gem
 .bundle
-Gemfile.lock
 pkg/*
 *~
 .yardoc/*

data/Gemfile

@@ -1,7 +1,7 @@
 source "http://rubygems.org"
 
-group :development, :test do
-  gem 'rspec'
+group :development do
+  gem "rspec", "~> 2.12.0"
 end
 
 gemspec

data/Gemfile.lock

@@ -0,0 +1,25 @@
+PATH
+  remote: .
+  specs:
+    seh (0.2.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.1)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  rspec (~> 2.12.0)
+  seh!

data/README.md

@@ -1,13 +1,87 @@
 
-# seh: structured event handler
+# Seh
+
+Structured event handler. Pure ruby event handling similar to w3c dom events. Check out `examples/epic_battle.rb`
+
+## Why Seh?
+
+Seh was developed as a dependency of my ruby game engine. I couldn't find another ruby event library with the features I wanted.
+
+You might want to use Seh if:
+* You need events/hooks/triggers/slots+signals
+* You need a synchronous system, because an event must be fully resolved before things can continue
+* An object/target/actor/thing might be affected by other things it doesn't know about
+* Your objects have underlying hierarchical / graph / observer relationships
+* You're hoping for *complex emergent behaviors*
+
+You probably don't want to use Seh if:
+* You need distributed or asynchronous events/hooks/triggers/slots+signals
+* You're thinking "gee, this seems complicated, I really just need simple hooks" -> Seh is probably over-engineering for you
+
+## Features
+
+Seh is driven by `Seh::Event` objects targeting objects of type `Seh::EventTarget`. Events are typed using `Seh::EventType` (which is mostly used implicitly).
+
+In most event systems, such as w3c dom events in a web browser, events are handled by child nodes before the event bubbles to ancestor nodes.  In Seh, each `EventTarget` which sees the `Event` may add callbacks to the event, *before any callbacks on the event are executed*. After each `EventTarget` has been visited, the `Event` executes its callbacks. This allows an ancestor object to affect an outcome on a descendant.
+
+Major Features
+* `EventTarget` is a mixin allowing any object to be the target of an `Event`
+* Create an `Event`, add some targets - objects which mixin `EventTarget` - and dispatch the event.  Each `Event` is one-use-only
+* `Event` has a list of types, e.g. :snow, :bad_weather, :sunshine; Types may be any object which defines equality ==
+* Bind callbacks to an `EventTarget`, e.g. `my_target.bind(:snow) { "It's snowing!" }`
+* Bind target callbacks using a type boolean expression, e.g. `my_target.bind( Seh::or :hurricane, Seh::and(:rain, :sunshine, Seh::not(:cold)) ) { 
+"It's either a hurricane, or sunny and raining and not cold." }`
+* Disconnect callback binds, `my_bind = my_target.bind(:only_needed) { "for awhile" }; my_bind.disconnect`
+* `EventTarget#observers` defaults to `[]`, and can be overridden to create an object graph. Each `EventTarget` recursively reachable by `EventTarget#observers` receives the event as if it was a top-level target.
+* `Event` makes it easy for events to "inherit" from one another, so that you may develop a rich event hierarchy on your application side. Note that there's no real ruby class inheritance, e.g. in `examples/event/`, the `Event::damage()` method calls `Event::hostile()`, making each damage event a hostile event.
+* `Event` inherits from `OpenStruct` to easily define attributes on the event
+* Event stages provide fine-grained control over callbacks
+
+## Understanding Event Stages & Callbacks
+
+See `Seh::Event#dispatch`. When `#dispach` is called:
+
+1. determine the full set of targets affected by this event
+2. run callbacks on targets which match this event's types
+3. run stage callbacks contained in this event; typically targets will append stage callbacks to this event using Event#bind, #start, #finish
+4. Callback execution order: (1) start callbacks; (2) stage callbacks - in the order stages were added to the event; (3) finish callbacks
+
+```ruby
+target = Seh::EventTarget::Default.new # Default includes EventTarget
+target.bind(:fireball) do |event| 
+  puts "1"
+  event.finish { puts "4" }
+end
+
+event = Seh::Event.new
+event.type :fireball
+event.target target
+event.start { puts "2" }
+
+event.add_stage :burn_enemy
+event.bind(:burn_enemy) { puts "3" }
+
+event.dispatch
+```
+
+The output of the above code is:
+
+```ruby
+1
+2
+3
+4
+```
 
 ## Roadmap
-* documentation
-* unit tests (my bad)
-* examples
 
-## v0.1.0
-seh API is fully implemented :)
+I'm working on efficiency, so tens of thousands of events can be used each second in a game engine.  There's a toy benchmark in 'rake benchmark'.
+
+## Release Notes
+
+* v0.3.0 - updated api, significantly expanded test coverage, documentation, examples, released under the [BSD license](http://opensource.org/licenses/BSD-3-Clause).
+* v0.1.0 - an older version of the API that's not backwards-compatible
+
+## License
 
-## Contact
-Please send (welcome) feedback and bug reports to ryan.berckmans@gmail.com.
+Seh is released under the [BSD license](http://opensource.org/licenses/BSD-3-Clause).

data/Rakefile

@@ -1 +1,32 @@
+require 'rake'
 require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+desc "run a simple Seh benchmark"
+task :benchmark do
+  $:.unshift File.expand_path(File.dirname(__FILE__) + "/examples")
+  require 'seh'
+  require_relative 'examples/mob'
+  require_relative 'examples/event/damage'
+
+  bob = Mob.new
+  fred = Mob.new
+
+  damage_shield = Seh::EventTarget::Default.new
+  damage_shield.bind(:damage) { |event| event.start { event.damage_add -= 0 } }
+  bob.observers << damage_shield
+
+  fred.bind(:hostile) { "oh no, hostile on fred" }
+  
+  start_time = Time.now
+  100000.times do
+    e = Seh::Event.new
+    Event::damage e, bob, fred, 0
+    e.dispatch
+  end
+  puts "took: #{Time.now - start_time}"
+end

data/examples/epic_battle.rb

@@ -0,0 +1,240 @@
+#!/usr/bin/env ruby
+
+require 'seh'
+require_relative 'event'
+require_relative 'event_color'
+
+# run ruby examples/epic_battle.rb
+#
+# The output is colorized to help visualize the Seh::Event objects.
+#
+# This example uses most of the Seh API and simulates a battle between two combatants, Fred and Jim.
+# Fred and Jim will continue melee-attacking each other until one is dead. Each has abilities which dynamically influence the result of the combat.
+#
+# examples/event/hostile.rb is a template for a Seh::Event representing a hostile action
+#
+# examples/event/damage.rb is a template for a Seh::Event representing one combatant doing damage to another. damage.rb calls hostile.rb, making each damage event also a hostile event.
+#
+# examples/event/melee_attack.rb is a template for a Seh::Event representing an attempted melee attack by one combatant on another. A successfully melee attack will create and dispach a new damage event, representing the damage inflicted by the strike.
+#
+# A melee attack may be thwarted by a dodge or riposte, which are modeled as callbacks on melee_attack events. The melee attack event has no direct knowledge that it may be affected by a dodge or riposte.
+#
+# Damage may be reduced by the shield of the ancients ability, or reflected by the reflexive barrier ability. The damage event has no direct knowledge of these abilities, which are modeled as callbacks.
+#
+# The battle is orated by BenevolentOverlord, a singleton which is wired to Combatant#observers.  This causes BenevolentOverlord to receive each event targeting any instance of Combatant.
+#
+
+# An observer which reports on the battle. BenevolentOverlord sees each event affecting any Combatant due to Combatant#observers
+class BenevolentOverlord
+  include Seh::EventTarget
+  def initialize
+    melee_battle_damage_callbacks
+    melee_battle_hostile_callbacks
+    melee_battle_melee_attack_callbacks
+  end
+
+  def melee_battle_melee_attack_callbacks
+    bind :melee_attack do |event|
+      event.bind :melee_miss do
+        puts_color_event event.object_id, "#{event.attacker} misses #{event.defender}. (event id #{event.object_id})"
+      end
+      
+      event.bind :melee_hit do
+        puts_color_event event.object_id, "#{event.attacker} successfully hits #{event.defender} for an initial damage of #{event.attack_damage}! (event id #{event.object_id})"
+      end
+    end
+  end
+
+  def melee_battle_damage_callbacks
+    bind :damage do |event|
+      event.start { puts_color_event event.object_id, "#{event.damager} tries to do #{event.damage} damage to #{event.receiver} (event id #{event.object_id})" }
+      event.finish { puts_color_event event.object_id, "#{event.damager} did #{event.damage > 0 ? event.damage : 0} damage to #{event.receiver} (event id #{event.object_id})" }
+    end
+  end
+
+  def melee_battle_hostile_callbacks
+    bind :hostile do |event|
+      # hostile is pretty spammy so comment it out
+      # event.start { puts_color_event event.object_id, "hostile start: #{event.aggressor} on #{event.aggressee} (event id #{event.object_id})" }
+      # event.finish { puts_color_event event.object_id, "hostile finish: #{event.aggressor} on #{event.aggressee} (event id #{event.object_id})" }
+    end
+  end
+
+  INSTANCE = BenevolentOverlord.new
+end
+
+class Combatant
+  include Seh::EventTarget
+  
+  attr_accessor :name, :hp, :affects
+  def initialize name
+    @name = name
+    @hp = 40
+    @affects = {}
+  end
+
+  def observers
+    [BenevolentOverlord::INSTANCE]
+  end
+
+  def to_s
+    @name
+  end
+end
+
+def coin_flip
+  Random.rand(2) > 0
+end
+
+def roll_damage
+  Random.rand(40) + 1
+end
+
+class CombatantDied < Exception
+  attr_reader :combatant
+  def initialize combatant
+    @combatant = combatant
+  end
+end
+
+def melee_attack attacker, defender
+  melee_attack_event = Seh::Event.new
+  Event::melee_attack melee_attack_event, attacker, defender, coin_flip, roll_damage
+  melee_attack_event.dispatch
+  raise CombatantDied, attacker if attacker.hp < 1
+  raise CombatantDied, defender if defender.hp < 1
+end
+
+############################
+# rpg/effects.rb
+
+# grant combatant the ability to dodge melee attacks
+def dodge combatant
+  puts "#{combatant} gains the ability to dodge"
+  combatant.bind :melee_attack do |event|
+    event.bind :melee_determine_hit do
+      if event.defender == combatant && event.attack_hit && coin_flip
+        event.attack_hit = false
+        event.abort
+        puts_color_event event.object_id, "#{event.attacker} narrowly misses #{event.defender}, who dodges! (event id #{event.object_id})"
+      end
+    end
+  end
+end
+
+# grant combatant the ability to riposte, i.e. to block and counterattack a melee attack
+def riposte combatant
+  puts "#{combatant} gains the ability to riposte"
+  combatant.bind :melee_attack do |event|
+    event.bind :melee_determine_hit do
+      if event.defender == combatant && event.attack_hit && coin_flip && coin_flip
+        event.attack_hit = false
+        event.abort
+        puts_color_event event.object_id, "#{event.attacker} attacks #{event.defender}, who parries and responds with a lightning-fast riposte! (event id #{event.object_id})"
+        melee_attack event.defender, event.attacker
+      end
+    end
+  end
+end
+
+# reduce incoming damage
+SHIELD_AMOUNT = 12
+def shield_of_the_ancients combatant
+  return if combatant.affects.key? :shield_of_ancients
+  puts "#{combatant} casts shield of the ancients"
+  combatant.affects[:shield_of_ancients] = combatant.bind(:damage) do |event|
+    event.bind :damage_modify do
+      next unless event.receiver == combatant
+      event.damage_reduction += SHIELD_AMOUNT
+      puts_color_event event.object_id, "#{combatant}'s shield of the ancients reduces his damage taken by #{SHIELD_AMOUNT} (event id #{event.object_id})"
+    end
+  end
+end
+
+# for one damage event, reverse the damage back to the damager
+def reflexive_barrier combatant
+  return if combatant.affects.key? :reflexive_barrier
+  puts "#{combatant} casts reflexive barrier"
+  combatant.affects[:reflexive_barrier] = combatant.bind(:damage) do |event|
+    event.bind :damage_targets do
+      next unless event.receiver == combatant
+      temp = event.damager
+      event.damager = event.receiver
+      event.receiver = temp
+      puts_color_event event.object_id, "#{combatant} uses his reflexive barrier to reflect damage back at #{event.receiver} (event id #{event.object_id})"
+      combatant.affects[:reflexive_barrier].disconnect
+      combatant.affects.delete :reflexive_barrier
+    end
+  end
+end
+
+# disable the next hostile action when the aggressee is the combatant
+def serenity combatant
+  return if combatant.affects.key? :serenity
+  puts "#{combatant}: casting serenity"
+  combatant.affects[:serenity] = combatant.bind :hostile do |event|
+    next unless event.aggressee == combatant
+    event.abort 
+    puts_color_event event.object_id, "#{combatant}'s serenity prevents hostile action by #{event.aggressor} (event id #{event.object_id})"
+    combatant.affects[:serenity].disconnect
+    combatant.affects.delete :serenity
+  end
+end
+
+def permanent_affects combatant
+  shield_of_the_ancients combatant if coin_flip
+  dodge combatant if coin_flip
+  riposte combatant if coin_flip
+end
+
+def onetime_affects combatant
+  reflexive_barrier combatant if coin_flip && coin_flip && coin_flip
+  serenity combatant if coin_flip && coin_flip && coin_flip
+end
+
+############################
+# put example all together
+
+def run
+  def status *combatants
+    s = ''
+    combatants.each { |m| s += m.to_s + ": " + m.hp.to_s + 'hp; ' }
+    puts s
+  end
+
+  2.times do
+    fred = Combatant.new "Fred"
+    jim  = Combatant.new "Jim"
+    puts "#{fred} and #{jim} rush into furious combat!"
+
+    permanent_affects fred
+    permanent_affects jim
+
+    begin
+      status fred, jim
+
+      onetime_affects fred
+      onetime_affects jim
+      
+      if coin_flip
+        first = fred
+        second = jim
+      else
+        first = jim
+        second = fred
+      end
+      
+      melee_attack first, second
+      melee_attack second, first
+      melee_attack first, second if coin_flip
+      melee_attack second, first if coin_flip
+    rescue CombatantDied => died
+      puts "#{died.combatant} died!\n\n"
+      break
+    end while true
+    puts "Myerael, arch-angel of battle, reincarnates #{fred} and #{jim}.."
+  end
+  puts "..and promptly slays them. The end."
+end
+
+run if $0 == __FILE__

data/examples/event.rb

@@ -0,0 +1 @@
+Dir[File.dirname(__FILE__) + '/event/*.rb'].each {|file| require file }

data/examples/event/damage.rb

@@ -0,0 +1,31 @@
+require "seh"
+require_relative "hostile"
+
+module Event
+  class << self
+    def damage event, damager, receiver, damage
+      hostile event, damager, receiver
+      
+      event.target damager, receiver
+      event.type :damage
+      event.damager = damager
+      event.receiver = receiver
+      
+      event.damage = damage
+      event.damage_add = 0 # bonus damage
+      event.damage_multiply = 1.0 # % bonus damage and stacks with damage_add
+      event.damage_reduction = 0 # directly subtracted from semifinal damage
+
+      event.add_stage :damage_targets # use stage to modify event.damager/receiver
+      event.add_stage :damage_modify # use stage to modify event.damage_add, damage_multiply, damage_reduction
+      event.add_stage :damage_apply # damage is applied during this stage, do not interfere
+
+      event.bind :damage_apply do
+        final_damage = ((event.damage + event.damage_add) * event.damage_multiply - event.damage_reduction).round
+        event.receiver.hp -= final_damage if final_damage > 0 # as a design decision, don't allow negative damage to heal
+        event.damage = final_damage
+      end
+      event
+    end
+  end
+end