Synced with 1.14

1 files changed, 178 insertions, 40 deletions

diff --git a/docs/docs.txt b/docs/docs.txt
index 0fe3d6d..6b94787 100644
--- a/docs/docs.txt
+++ b/docs/docs.txt
@@ -887,7 +887,7 @@ to clarify some terms. Specifically _language specification_ vs _runtime_.
 
 *** Okay... so what is the difference between a language specification and a runtime?
 
-A runtime is an _implementation_ of a langauge specification. When
+A runtime is an _implementation_ of a language specification. When
 people say "Ruby," they are usually referring to "the Ruby 3.0+ language
 specification implemented via the CRuby/MRI Runtime."
 
@@ -923,18 +923,18 @@ runtime internally):
   C-Extensions.
 
 Levels 1 through 3 are fairly commonplace in many runtime
-implemenations (with level 1 being the most portable, and level 3
+implementations (with level 1 being the most portable, and level 3
 being the fastest). But the DragonRuby Runtime has taken things a
 bit further:
 
 - Level 4 consists of shared abstractions around hardware I/O and operating
   system resources. This level leverages open source and proprietary
-  components within Simple DirectMedia Layer (a lowlevel multimedia
+  components within Simple DirectMedia Layer (a low level multimedia
   component library that has been in active development for 22 years
   and counting).
 
-- Level 5 is a codegeneration layer which creates metadata that allows
-  for native interopability with host runtime libraries. It also
+- Level 5 is a code generation layer which creates metadata that allows
+  for native interoperability with host runtime libraries. It also
   includes OS specific message pump orchestrations.
 
 - Level 6 is a Ahead of Time/Just in Time Ruby compiler built with LLVM. This
@@ -943,12 +943,12 @@ bit further:
 
 These levels allow us to stay up to date with open source
 implementations of Ruby; provide fast, native code execution
-on proprietary platforms; ensure good seperation between these two
+on proprietary platforms; ensure good separation between these two
 worlds; and provides a means to add new platforms without going insane.
 
 *** Cool cool. So given that I understand everything to this point, can we answer the original question? What is DragonRuby?
 
-DragonRuby is a Ruby runtime implentation that takes all the lessons
+DragonRuby is a Ruby runtime implementation that takes all the lessons
 we've learned from MRI/CRuby, and merges it with the latest and greatest
 compiler and OSS technologies.
 
@@ -973,30 +973,30 @@ That doesn't make any sense. A language specification can't be
 slow... it's a language spec. Sure, an _implementation/runtime_ can be slow though, but then we'd
 have to talk about which runtime.
 
-*** Dynamic langauges are slow.
+*** Dynamic languages are slow.
 
 They are certainly slower than statically compiled languages. With the
 processing power and compiler optimizations we have today,
 dynamic languages like Ruby are _fast enough_.
 
 Unless you are writing in some form of intermediate representation by hand,
-your langauge of choice also suffers this same fallacy of slow. Like, nothing is
+your language of choice also suffers this same fallacy of slow. Like, nothing is
 faster than a low level assembly-like language. So unless you're
 writing in that, let's stop making this comment.
 
 NOTE: If you _are_ hand writing LLVM IR, we are always open to
-bringing on new partners with such a skillset. Email us ^_^.
+bringing on new partners with such a skill set. Email us ^_^.
 
 ** Frequent Concerns
 
 *** DragonRuby is not open source. That's not right.
 
 The current state of open source is unsustainable. Contributors work
-for free, most all open source repositories are serverly understaffed,
+for free, most all open source repositories are severely under-staffed,
 and burnout from core members is rampant.
 
 We believe in open source very strongly. Parts of DragonRuby are
-infact, open source. Just not all of it (for legal reasons, and
+in fact, open source. Just not all of it (for legal reasons, and
 because the IP we've created has value). And we promise that we are
 looking for (or creating) ways to _sustainably_ open source everything we do.
 
@@ -1047,7 +1047,7 @@ email. We don't want to collect usage data off of you either. We just
 want to provide quality toolchains to quality developers (as opposed
 to a large quantity of developers).
 
-The peiple that pay for DragonRuby and make an effort to understand it are the
+The people that pay for DragonRuby and make an effort to understand it are the
 ones we want to build a community around, partner with, and collaborate
 with. So having that small monetary wall deters entitled individuals
 that don't value the same things we do.
@@ -1059,7 +1059,7 @@ and non-trivially compensate open source developers. Look, we want to be
 able to work on the stuff we love, every day of our lives. And we'll go
 to great lengths to make that happen.
 
-But, in the event that sad day comes, our partnershiop bylaws state that
+But, in the event that sad day comes, our partnership bylaws state that
 _all_ DragonRuby IP that can be legally open sourced, will be released
 under a permissive license.
 
@@ -1341,32 +1341,6 @@ mygame/app/main.rb
 #+end_src
 
 
-* DOCS: ~GTK::Outputs#borders~
-
-Add primitives to this collection to render an unfilled solid to the screen. Take a look at the
-documentation for Outputs#solids.
-
-The only difference between the two primitives is where they are added.
-
-Instead of using ~args.outputs.solids~:
-
-#+begin_src
-  def tick args
-    #                         X    Y  WIDTH  HEIGHT
-    args.outputs.solids << [100, 100,   160,     90]
-  end
-#+end_src
-
-You have to use ~args.outputs.borders~:
-
-#+begin_src
-  def tick args
-    #                           X    Y  WIDTH  HEIGHT
-    args.outputs.borders << [100, 100,   160,     90]
-  end
-#+end_src
-
-
 * DOCS: ~GTK::Outputs#solids~
 
 Add primitives to this collection to render a solid to the screen.
@@ -1454,6 +1428,32 @@ Here is an example:
 #+end_src
 
 
+* DOCS: ~GTK::Outputs#borders~
+
+Add primitives to this collection to render an unfilled solid to the screen. Take a look at the
+documentation for Outputs#solids.
+
+The only difference between the two primitives is where they are added.
+
+Instead of using ~args.outputs.solids~:
+
+#+begin_src
+  def tick args
+    #                         X    Y  WIDTH  HEIGHT
+    args.outputs.solids << [100, 100,   160,     90]
+  end
+#+end_src
+
+You have to use ~args.outputs.borders~:
+
+#+begin_src
+  def tick args
+    #                           X    Y  WIDTH  HEIGHT
+    args.outputs.borders << [100, 100,   160,     90]
+  end
+#+end_src
+
+
 * DOCS: ~GTK::Mouse~
 
 The mouse is accessible via ~args.inputs.mouse~:
@@ -1629,6 +1629,144 @@ Example using named parameters:
 #+end_src
 
 
+* DOCS: ~Numeric#elapsed_time~
+For a given number, the elapsed frames since that number is returned.
+`Kernel.tick_count` is used to determine how many frames have elapsed.
+An optional numeric argument can be passed in which will be used instead
+of `Kernel.tick_count`.
+
+Here is an example of how elapsed_time can be used.
+
+#+begin_src ruby
+  def tick args
+    args.state.last_click_at ||= 0
+
+    # record when a mouse click occurs
+    if args.inputs.mouse.click
+      args.state.last_click_at = args.state.tick_count
+    end
+
+    # Use Numeric#elapsed_time to determine how long it's been
+    if args.state.last_click_at.elapsed_time > 120
+      args.outputs.labels << [10, 710, "It has been over 2 seconds since the mouse was clicked."]
+    end
+  end
+#+end_src
+
+And here is an example where the override parameter is passed in:
+
+#+begin_src ruby
+  def tick args
+    args.state.last_click_at ||= 0
+
+    # create a state variable that tracks time at half the speed of args.state.tick_count
+    args.state.simulation_tick = args.state.tick_count.idiv 2
+
+    # record when a mouse click occurs
+    if args.inputs.mouse.click
+      args.state.last_click_at = args.state.simulation_tick
+    end
+
+    # Use Numeric#elapsed_time to determine how long it's been
+    if (args.state.last_click_at.elapsed_time args.state.simulation_tick) > 120
+      args.outputs.labels << [10, 710, "It has been over 4 seconds since the mouse was clicked."]
+    end
+  end
+#+end_src
+
+
+* DOCS: ~Numeric#elapsed?~
+Returns true if ~Numeric#elapsed_time~ is greater than the number. An optional parameter can be
+passed into ~elapsed?~ which is added to the number before evaluating whether ~elapsed?~ is true.
+
+Example usage (no optional parameter):
+
+#+begin_src ruby
+  def tick args
+    args.state.box_queue ||= []
+
+    if args.state.box_queue.empty?
+      args.state.box_queue << { name: :red,
+                                destroy_at: args.state.tick_count + 60 }
+      args.state.box_queue << { name: :green,
+                                destroy_at: args.state.tick_count + 60 }
+      args.state.box_queue << { name: :blue,
+                                destroy_at: args.state.tick_count + 120 }
+    end
+
+    boxes_to_destroy = args.state
+                           .box_queue
+                           .find_all { |b| b[:destroy_at].elapsed? }
+
+    if !boxes_to_destroy.empty?
+      puts "boxes to destroy count: #{boxes_to_destroy.length}"
+    end
+
+    boxes_to_destroy.each { |b| puts "box #{b} was elapsed? on #{args.state.tick_count}." }
+
+    args.state.box_queue -= boxes_to_destroy
+  end
+#+end_src
+
+Example usage (with optional parameter):
+
+#+begin_src ruby
+  def tick args
+    args.state.box_queue ||= []
+
+    if args.state.box_queue.empty?
+      args.state.box_queue << { name: :red,
+                                create_at: args.state.tick_count + 120,
+                                lifespan: 60 }
+      args.state.box_queue << { name: :green,
+                                create_at: args.state.tick_count + 120,
+                                lifespan: 60 }
+      args.state.box_queue << { name: :blue,
+                                create_at: args.state.tick_count + 120,
+                                lifespan: 120 }
+    end
+
+    # lifespan is passed in as a parameter to ~elapsed?~
+    boxes_to_destroy = args.state
+                           .box_queue
+                           .find_all { |b| b[:create_at].elapsed? b[:lifespan] }
+
+    if !boxes_to_destroy.empty?
+      puts "boxes to destroy count: #{boxes_to_destroy.length}"
+    end
+
+    boxes_to_destroy.each { |b| puts "box #{b} was elapsed? on #{args.state.tick_count}." }
+
+    args.state.box_queue -= boxes_to_destroy
+  end
+#+end_src
+
+
+* DOCS: ~Numeric#created?~
+Returns true if ~Numeric#elapsed_time == 0~. Essentially communicating that
+number is equal to the current frame.
+
+Example usage:
+
+#+begin_src ruby
+  def tick args
+    args.state.box_queue ||= []
+
+    if args.state.box_queue.empty?
+      args.state.box_queue << { name: :red,
+                                create_at: args.state.tick_count + 60 }
+    end
+
+    boxes_to_spawn_this_frame = args.state
+                                    .box_queue
+                                    .find_all { |b| b[:create_at].new? }
+
+    boxes_to_spawn_this_frame.each { |b| puts "box #{b} was new? on #{args.state.tick_count}." }
+
+    args.state.box_queue -= boxes_to_spawn_this_frame
+  end
+#+end_src
+
 * DOCS: ~Kernel~
 
 Kernel in the DragonRuby Runtime has patches for how standard out is handled and also