draco 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1886b23bb2d098362aa4452b25922fc98fb033fd86f0b8360586da1406bd5810
-  data.tar.gz: 9c0e7314c301c7b879ec71bbe8eb8966b04d6c85093d176a2d0c658cb0ad5b0b
+  metadata.gz: 9c330a2195d1f7b17f0bb1be16914cef57ccfcf5094ed034cf50a64a3abae52a
+  data.tar.gz: efa72ad0c7facd4c3143f858a07adc5be8e6b225635d54b4b60fc983343f33be
 SHA512:
-  metadata.gz: 29ebe2a5000a3966d4269df1ee0fb7046b0c830f8f5ed589e918d953665da8e0d1f8992d71fb9f2f2b76339fd390821f4732b60488f84daad6ceec3638caa715
-  data.tar.gz: 3f617f62d43e4c680a7983278b465cf5498594883581ad0571368a10ef59e80a35969a1c7cdfbdab114ee808b718782433e467761fdf8fc952229643d6d2e27e
+  metadata.gz: b5223959feeb20099bca35233f704b91270757ed33d1f59cd3091e6ea8793bb28a3cc4467670ac305931f85c5bb12fe036ac2ae2655aa8c597e5d02ff3d19993
+  data.tar.gz: cb182bfbcbe2b69fc5a84adf2aceabc1dddc7d75c2159cb4b13fcfb4f3f3ead4659dd1d6e114152c8ba61c8d8100672fa2672b65b267feb413ff0aece91caf42

data/.gitignore

@@ -9,3 +9,5 @@
 
 # rspec failure tracking
 .rspec_status
+
+.vscode/

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 0.6.0
+
+Features:
+
+  - `#serialize` now includes the class name for Entities, Components, and Systems.
+  - Added callbacks to Entities, Components, Systems and Worlds to better enable plugins.
+  - Added a sample plugin to `lib/draco/benchmark.rb` to benchmark your systems.
+
+    How to use:
+
+    ```ruby
+    class World < Draco::World
+      include Draco::Benchmark
+    end
+
+    world.system_timers
+    # => { :system => 0.001 }
+    ```
+
 ## 0.5.1 (December 31, 2020)
 
 Features:

data/Gemfile.lock

@@ -3,43 +3,45 @@ GEM
   specs:
     ast (2.4.1)
     diff-lcs (1.4.4)
-    docile (1.3.2)
-    parallel (1.19.2)
-    parser (2.7.2.0)
+    docile (1.3.4)
+    parallel (1.20.1)
+    parser (3.0.0.0)
       ast (~> 2.4.1)
     rainbow (3.0.0)
     rake (12.3.3)
-    regexp_parser (1.8.2)
+    regexp_parser (2.0.3)
     rexml (3.2.4)
     rspec (3.10.0)
       rspec-core (~> 3.10.0)
       rspec-expectations (~> 3.10.0)
       rspec-mocks (~> 3.10.0)
-    rspec-core (3.10.0)
+    rspec-core (3.10.1)
       rspec-support (~> 3.10.0)
-    rspec-expectations (3.10.0)
+    rspec-expectations (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.0)
+    rspec-mocks (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
-    rspec-support (3.10.0)
-    rubocop (1.2.0)
+    rspec-support (3.10.1)
+    rubocop (1.7.0)
       parallel (~> 1.10)
       parser (>= 2.7.1.5)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8)
+      regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.0.1)
+      rubocop-ast (>= 1.2.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-ast (1.1.1)
+    rubocop-ast (1.4.0)
       parser (>= 2.7.1.5)
-    ruby-progressbar (1.10.1)
-    simplecov (0.19.0)
+    ruby-progressbar (1.11.0)
+    simplecov (0.21.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
-    simplecov-html (0.12.2)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.2)
     unicode-display_width (1.7.0)
 
 PLATFORMS
@@ -52,4 +54,4 @@ DEPENDENCIES
   simplecov
 
 BUNDLED WITH
-   2.1.4
+   2.2.3

data/README.md

@@ -8,14 +8,17 @@ objects.
 
 ## Sample Application
 
-This repository includes a sample application in `samples/teeny-tiny`.
+This repository includes sample applications in the `samples/` directory.
+
+* teeny-tiny - A 20 second space shooter created during the DragonRuby TeenyTiny Game Jam
+* gorillas-basic - A recreation of the gorillas_basic sample game that comes with DragonRuby
 
 ### Running the sample application
 
 1. Download the [latest release](https://github.com/guitsaru/draco/archive/main.zip) of this repository.
 2. Create a copy of DragonRuby GTK in a new folder.
-3. Copy the teeny-tiny directory from draco into your new DragonRuby GTK folder. `cp -r draco/samples/teeny-tiny dragonruby/teeny-tiny`.
-4. Run it using `./dragonruby teeny-tiny`.
+3. Copy the teeny-tiny directory from draco into your new DragonRuby GTK folder. `cp -r draco/samples/ dragonruby/`.
+4. Run them using `./dragonruby teeny-tiny` or `./dragonruby gorillas-basic`.
 
 ## Installation
 

data/lib/draco.rb

@@ -4,8 +4,10 @@
 #
 # An Entity Component System is an architectural pattern used in game development to decouple behavior from objects.
 module Draco
+  class NotAComponentError < StandardError; end
+
   # Public: The version of the library. Draco uses semver to version releases.
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 
   # Public: A general purpose game object that consists of a unique id and a collection of Components.
   class Entity
@@ -73,15 +75,33 @@ module Draco
     def initialize(args = {})
       @id = args.fetch(:id, @@next_id)
       @@next_id = [@id + 1, @@next_id].max
-      @components = ComponentStore.new(self)
       @subscriptions = []
 
+      setup_components(args)
+      after_initialize
+    end
+
+    # Internal: Sets up the default components for the class.
+    #
+    # args - A hash of arguments to pass into the generated components.
+    #
+    # Returns nothing.
+    def setup_components(args)
+      @components = ComponentStore.new(self)
+
       self.class.default_components.each do |component, default_args|
         arguments = default_args.merge(args[Draco.underscore(component.name.to_s).to_sym] || {})
         @components << component.new(arguments)
       end
     end
 
+    # Public: Callback run after the entity is initialized.
+    #
+    # This is empty by default but is present to allow plugins to tie into.
+    #
+    # Returns nothing.
+    def after_initialize; end
+
     # Public: Subscribe to an Entity's Component updates.
     #
     # subscriber - The object to notify when Components change.
@@ -91,18 +111,49 @@ module Draco
       @subscriptions << subscriber
     end
 
-    # Internal: Notifies subscribers that components have been updated.
+    # Public: Callback run before a component is added.
     #
-    # Returns nothing.
-    def components_updated
-      @subscriptions.each { |sub| sub.entity_updated(self) }
+    # component - The component that will be added.
+    #
+    # Returns the component to add.
+    def before_component_added(component)
+      component
+    end
+
+    # Public: Callback run after a component is added.
+    #
+    # component - The component that was added.
+    #
+    # Returns the added component.
+    def after_component_added(component)
+      @subscriptions.each { |sub| sub.component_added(self, component) }
+      component
+    end
+
+    # Public: Callback run before a component is deleted.
+    #
+    # component - The component that will be removed.
+    #
+    # Returns the component to remove.
+    def before_component_removed(component)
+      component
+    end
+
+    # Public: Callback run after a component is deleted.
+    #
+    # component - The component that was removed.
+    #
+    # Returns the removed component.
+    def after_component_removed(component)
+      @subscriptions.each { |sub| sub.component_removed(self, component) }
+      component
     end
 
     # Public: Serializes the Entity to save the current state.
     #
     # Returns a Hash representing the Entity.
     def serialize
-      serialized = { id: id }
+      serialized = { class: self.class.name.to_s, id: id }
 
       components.each do |component|
         serialized[Draco.underscore(component.class.name.to_s).to_sym] = component.serialize
@@ -174,7 +225,6 @@ module Draco
       def <<(*components)
         components.flatten.each { |component| add(component) }
 
-        @parent.components_updated
         self
       end
 
@@ -195,10 +245,16 @@ module Draco
       #
       # Returns the ComponentStore.
       def add(component)
+        unless component.is_a?(Draco::Component)
+          message = component.is_a?(Class) ? " You might need to initialize the component before you add it." : ""
+          raise Draco::NotAComponentError, "The given value is not a component.#{message}"
+        end
+
+        component = @parent.before_component_added(component)
         name = Draco.underscore(component.class.name.to_s).to_sym
         @components[name] = component
+        @parent.after_component_added(component)
 
-        @parent.components_updated
         self
       end
 
@@ -210,10 +266,11 @@ module Draco
       #
       # Returns the ComponentStore.
       def delete(component)
+        component = @parent.before_component_removed(component)
         name = Draco.underscore(component.class.name.to_s).to_sym
         @components.delete(name)
+        @parent.after_component_removed(component)
 
-        @parent.components_updated
         self
       end
 
@@ -264,6 +321,15 @@ module Draco
       attr_reader :attribute_options
     end
 
+    # Public: Creates a tag Component. If the tag already exists, return it.
+    #
+    # name - The string or symbol name of the component.
+    #
+    # Returns a class with subclass Draco::Component.
+    def self.Tag(name) # rubocop:disable Naming/MethodName
+      Draco::Tag(name)
+    end
+
     # Public: Initializes a new Component.
     #
     # values - The Hash of values to set for the Component instance (default: {}).
@@ -282,13 +348,21 @@ module Draco
         value = values.fetch(name.to_sym, options[:default])
         instance_variable_set("@#{name}", value)
       end
+      after_initialize
     end
 
+    # Public: Callback run after the component is initialized.
+    #
+    # This is empty by default but is present to allow plugins to tie into.
+    #
+    # Returns nothing.
+    def after_initialize; end
+
     # Public: Serializes the Component to save the current state.
     #
     # Returns a Hash representing the Component.
     def serialize
-      attrs = {}
+      attrs = { class: self.class.name.to_s }
 
       instance_variables.each do |attr|
         name = attr.to_s.gsub("@", "").to_sym
@@ -371,8 +445,37 @@ module Draco
     def initialize(entities: [], world: nil)
       @entities = entities
       @world = world
+      after_initialize
     end
 
+    # Public: Callback run after the system is initialized.
+    #
+    # This is empty by default but is present to allow plugins to tie into.
+    #
+    # Returns nothing.
+    def after_initialize; end
+
+    # Public: Runs the system tick function.
+    #
+    # context - The context object of the current tick from the game engine. In DragonRuby this is `args`.
+    #
+    # Returns nothing.
+    def call(context)
+      before_tick(context)
+      tick(context)
+      after_tick(context)
+      self
+    end
+
+    # Public: Callback run before #tick is called.
+    #
+    # This is empty by default but is present to allow plugins to tie into.
+    #
+    # context - The context object of the current tick from the game engine. In DragonRuby this is `args`.
+    #
+    # Returns nothing.
+    def before_tick(context); end
+
     # Public: Runs the System logic for the current game engine tick.
     #
     # This is where the logic is implemented and it should be overriden for each System.
@@ -382,11 +485,19 @@ module Draco
     # Returns nothing
     def tick(context); end
 
+    # Public: Callback run after #tick is called.
+    #
+    # This is empty by default but is present to allow plugins to tie into.
+    #
+    # Returns nothing.
+    def after_tick(context); end
+
     # Public: Serializes the System to save the current state.
     #
     # Returns a Hash representing the System.
     def serialize
       {
+        class: self.class.name.to_s,
         entities: entities.map(&:serialize),
         world: world ? world.serialize : nil
       }
@@ -481,8 +592,29 @@ module Draco
         entity
       end
 
-      @entities = EntityStore.new(default_entities + entities)
+      @entities = EntityStore.new(self, default_entities + entities)
       @systems = self.class.default_systems + systems
+      after_initialize
+    end
+
+    # Public: Callback run after the world is initialized.
+    #
+    # This is empty by default but is present to allow plugins to tie into.
+    #
+    # Returns nothing.
+    def after_initialize; end
+
+    # Public: Callback run before #tick is called.
+    #
+    # context - The context object of the current tick from the game engine. In DragonRuby this is `args`.
+    #
+    # Returns the systems to run during this tick.
+    def before_tick(_context)
+      systems.map do |system|
+        entities = filter(system.filter)
+
+        system.new(entities: entities, world: self)
+      end
     end
 
     # Public: Runs all of the Systems every tick.
@@ -491,13 +623,39 @@ module Draco
     #
     # Returns nothing
     def tick(context)
-      systems.each do |system|
-        entities = filter(system.filter)
-
-        system.new(entities: entities, world: self).tick(context)
+      results = before_tick(context).map do |system|
+        system.call(context)
       end
+
+      after_tick(context, results)
     end
 
+    # Public: Callback run after #tick is called.
+    #
+    # This is empty by default but is present to allow plugins to tie into.
+    #
+    # context - The context object of the current tick from the game engine. In DragonRuby this is `args`.
+    # results - The System instances that were run.
+    #
+    # Returns nothing.
+    def after_tick(context, results); end
+
+    # Public: Callback to run when a component is added to an existing Entity.
+    #
+    # entity - The Entity the Component was added to.
+    # component - The Component that was added to the Entity.
+    #
+    # Returns nothing.
+    def component_added(entity, component); end
+
+    # Public: Callback to run when a component is added to an existing Entity.
+    #
+    # entity - The Entity the Component was removed from.
+    # component - The Component that was removed from the Entity.
+    #
+    # Returns nothing.
+    def component_removed(entity, component); end
+
     # Public: Finds all Entities that contain all of the given Components.
     #
     # components - An Array of Component classes to match.
@@ -512,6 +670,7 @@ module Draco
     # Returns a Hash representing the World.
     def serialize
       {
+        class: self.class.name.to_s,
         entities: @entities.map(&:serialize),
         systems: @systems.map { |system| system.name.to_s }
       }
@@ -531,10 +690,13 @@ module Draco
     class EntityStore
       include Enumerable
 
+      attr_reader :parent
+
       # Internal: Initializes a new EntityStore
       #
       # entities - The Entities to add to the EntityStore
-      def initialize(*entities)
+      def initialize(parent, *entities)
+        @parent = parent
         @entity_to_components = Hash.new { |hash, key| hash[key] = Set.new }
         @component_to_entities = Hash.new { |hash, key| hash[key] = Set.new }
         @entity_ids = {}
@@ -586,13 +748,11 @@ module Draco
         entity.subscribe(self)
 
         @entity_ids[entity.id] = entity
-
         components = entity.components.map(&:class)
         @entity_to_components[entity].merge(components)
 
-        components.each do |component|
-          @component_to_entities[component].add(entity)
-        end
+        components.each { |component| @component_to_entities[component].add(entity) }
+        entity.components.each { |component| @parent.component_added(entity, component) }
 
         self
       end
@@ -621,21 +781,26 @@ module Draco
         @entity_to_components.keys.each(&block)
       end
 
-      # Internal: Updates the EntityStore when an Entity's Components are modified.
+      # Internal: Updates the EntityStore when an Entity's Components are added.
       #
-      # entity - The Entity whose Components were updated.
+      # entity - The Entity the Component was added to.
+      # component - The Component that was added to the Entity.
       #
       # Returns nothing.
-      def entity_updated(entity)
-        old = @entity_to_components[entity].to_a
-        components = entity.components.map(&:class)
-        @entity_to_components[entity] = components
-
-        added = components - old
-        deleted = old - components
+      def component_added(entity, component)
+        @component_to_entities[component.class].add(entity)
+        @parent.component_added(entity, component)
+      end
 
-        added.each { |component| @component_to_entities[component].add(entity) }
-        deleted.each { |component| @component_to_entities[component].delete(entity) }
+      # Internal: Updates the EntityStore when an Entity's Components are removed.
+      #
+      # entity - The Entity the Component was removed from.
+      # component - The Component that was removed from the Entity.
+      #
+      # Returns nothing.
+      def component_removed(entity, component)
+        @component_to_entities[component.class].delete(entity)
+        @parent.component_removed(entity, component)
       end
     end
   end

data/lib/draco/benchmark.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Draco
+  # Public: Calculates the average time of
+  module Benchmark
+    def self.included(mod)
+      mod.prepend(World)
+    end
+
+    # Internal: Plugin implementation for World.
+    module World
+      def before_tick(context)
+        super
+        @system_timer_data = Hash.new { |h, k| h[k] = [] }
+        @systems.each { |system| system.prepend(System) }
+      end
+
+      def after_tick(context, results)
+        super
+        results.each do |system|
+          name = Draco.underscore(system.class.name.to_s).to_sym
+          @system_timer_data[name] = (system.timer * 1000.0).round(5)
+        end
+      end
+
+      def system_timers
+        @system_timer_data.sort_by { |_k, v| -v }.to_h
+      end
+    end
+
+    # Internal: Plugin implementation for System.
+    module System
+      def after_initialize
+        super
+        @timer = 0
+      end
+
+      def before_tick(context)
+        super
+        @start_time = Time.now
+      end
+
+      def after_tick(context)
+        super
+        @timer = Time.now - @start_time
+      end
+
+      def timer
+        @timer
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: draco
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Matt Pruitt
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-12-31 00:00:00.000000000 Z
+date: 2021-01-05 00:00:00.000000000 Z
 dependencies: []
 description: A library for Entities, Components, and Systems in games.
 email:
@@ -35,6 +35,7 @@ files:
 - bin/setup
 - draco.gemspec
 - lib/draco.rb
+- lib/draco/benchmark.rb
 homepage: https://github.com/guitsaru/draco
 licenses: []
 metadata:
@@ -55,7 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: An ECS library.