Synced with 1.14

1 files changed, 170 insertions, 38 deletions

diff --git a/docs/docs.html b/docs/docs.html
index 1640d49..b92e9f8 100644
--- a/docs/docs.html
+++ b/docs/docs.html
@@ -40,13 +40,16 @@
 <li><a href='#--docs---array#include_any?-'><code>Array#include_any?</code></a></li>
 <li><a href='#--docs---array#any_intersect_rect?-'><code>Array#any_intersect_rect?</code></a></li>
 <li><a href='#--docs---gtk--outputs-'><code>GTK::Outputs</code></a></li>
-<li><a href='#--docs---gtk--outputs#borders-'><code>GTK::Outputs#borders</code></a></li>
 <li><a href='#--docs---gtk--outputs#solids-'><code>GTK::Outputs#solids</code></a></li>
+<li><a href='#--docs---gtk--outputs#borders-'><code>GTK::Outputs#borders</code></a></li>
 <li><a href='#--docs---gtk--mouse-'><code>GTK::Mouse</code></a></li>
 <li><a href='#--docs---gtk--mousepoint-'><code>GTK::MousePoint</code></a></li>
 <li><a href='#--docs---gtk--openentity-'><code>GTK::OpenEntity</code></a></li>
 <li><a href='#--docs---gtk--openentity#as_hash-'><code>GTK::OpenEntity#as_hash</code></a></li>
 <li><a href='#--docs---numeric#frame_index-'><code>Numeric#frame_index</code></a></li>
+<li><a href='#--docs---numeric#elapsed_time-'><code>Numeric#elapsed_time</code></a></li>
+<li><a href='#--docs---numeric#elapsed?-'><code>Numeric#elapsed?</code></a></li>
+<li><a href='#--docs---numeric#created?-'><code>Numeric#created?</code></a></li>
 <li><a href='#--docs---kernel-'><code>Kernel</code></a></li>
 <li><a href='#--docs---kernel--tick_count-'><code>Kernel::tick_count</code></a></li>
 <li><a href='#--docs---kernel--global_tick_count-'><code>Kernel::global_tick_count</code></a></li>
@@ -793,7 +796,7 @@ The response to this question requires a few subparts. First we need to clarify
 </p>
 <h3>Okay... so what is the difference between a language specification and a runtime?</h3>
 <p>
-A runtime is an _implementation_ of a langauge specification. When people say "Ruby," they are usually referring to "the Ruby 3.0+ language specification implemented via the CRuby/MRI Runtime."
+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."
 </p>
 <p>
 But, there are many Ruby Runtimes: CRuby/MRI, JRuby, Truffle, Rubinius, Artichoke, and (last but certainly not least) DragonRuby.
@@ -821,22 +824,22 @@ There are complexities associated with targeting all the platforms we support. B
   C-Extensions.</li>
 </ul>
 <p>
-Levels 1 through 3 are fairly commonplace in many runtime implemenations (with level 1 being the most portable, and level 3 being the fastest). But the DragonRuby Runtime has taken things a bit further:
+Levels 1 through 3 are fairly commonplace in many runtime implementations (with level 1 being the most portable, and level 3 being the fastest). But the DragonRuby Runtime has taken things a bit further:
 </p>
 <ul>
 <li>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   component library that has been in active development for 22 years   and counting).</li>
-<li>Level 5 is a codegeneration layer which creates metadata that allows
-  for native interopability with host runtime libraries. It also   includes OS specific message pump orchestrations.</li>
+  system resources. This level leverages open source and proprietary   components within Simple DirectMedia Layer (a low level multimedia   component library that has been in active development for 22 years   and counting).</li>
+<li>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.</li>
 <li>Level 6 is a Ahead of Time/Just in Time Ruby compiler built with LLVM. This
   compiler outputs _very_ fast platform specific bitcode, but only   supports a subset of the Ruby language specification.</li>
 </ul>
 <p>
-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 worlds; and provides a means to add new platforms without going insane.
+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 separation between these two worlds; and provides a means to add new platforms without going insane.
 </p>
 <h3>Cool cool. So given that I understand everything to this point, can we answer the original question? What is DragonRuby?</h3>
 <p>
-DragonRuby is a Ruby runtime implentation that takes all the lessons we've learned from MRI/CRuby, and merges it with the latest and greatest compiler and OSS technologies.
+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.
 </p>
 <h2>Frequent Comments</h2>
 <h3>But Ruby is dead.</h3>
@@ -856,23 +859,23 @@ Let's stop making this comment shall we?
 <p>
 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.
 </p>
-<h3>Dynamic langauges are slow.</h3>
+<h3>Dynamic languages are slow.</h3>
 <p>
 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_.
 </p>
 <p>
-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 faster than a low level assembly-like language. So unless you're writing in that, let's stop making this comment.
+Unless you are writing in some form of intermediate representation by hand, 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.
 </p>
 <p>
-NOTE: If you _are_ hand writing LLVM IR, we are always open to bringing on new partners with such a skillset. Email us ^_^.
+NOTE: If you _are_ hand writing LLVM IR, we are always open to bringing on new partners with such a skill set. Email us ^_^.
 </p>
 <h2>Frequent Concerns</h2>
 <h3>DragonRuby is not open source. That's not right.</h3>
 <p>
-The current state of open source is unsustainable. Contributors work for free, most all open source repositories are serverly understaffed, and burnout from core members is rampant.
+The current state of open source is unsustainable. Contributors work for free, most all open source repositories are severely under-staffed, and burnout from core members is rampant.
 </p>
 <p>
-We believe in open source very strongly. Parts of DragonRuby are infact, 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.
+We believe in open source very strongly. Parts of DragonRuby are 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.
 </p>
 <p>
 If you have ideas on how we can do this, email us!
@@ -914,14 +917,14 @@ Seriously just buy it. Get a refund if you don't like it. We make it stupid easy
 Free isn't a sustainable financial model. We don't want to spam your 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).
 </p>
 <p>
-The peiple 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.
+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.
 </p>
 <h3>What if I build something with DragonRuby, but DragonRuby LLP becomes insolvent.</h3>
 <p>
 That won't happen if the development world stop asking for free stuff 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.
 </p>
 <p>
-But, in the event that sad day comes, our partnershiop bylaws state that _all_ DragonRuby IP that can be legally open sourced, will be released under a permissive license.
+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.
 </p>
 <h1 id='--docs---gtk--runtime-'><code>GTK::Runtime</code></h1>
 <p>
@@ -1161,29 +1164,6 @@ Outputs is how you render primitives to the screen. The minimal setup for render
   # code goes here
 end
 </pre>
-<h1 id='--docs---gtk--outputs#borders-'><code>GTK::Outputs#borders</code></h1>
-<p>
-Add primitives to this collection to render an unfilled solid to the screen. Take a look at the documentation for Outputs#solids.
-</p>
-<p>
-The only difference between the two primitives is where they are added.
-</p>
-<p>
-Instead of using <code>args.outputs.solids</code>:
-</p>
-<pre>def tick args
-  #                         X    Y  WIDTH  HEIGHT
-  args.outputs.solids << [100, 100,   160,     90]
-end
-</pre>
-<p>
-You have to use <code>args.outputs.borders</code>:
-</p>
-<pre>def tick args
-  #                           X    Y  WIDTH  HEIGHT
-  args.outputs.borders << [100, 100,   160,     90]
-end
-</pre>
 <h1 id='--docs---gtk--outputs#solids-'><code>GTK::Outputs#solids</code></h1>
 <p>
 Add primitives to this collection to render a solid to the screen.
@@ -1258,6 +1238,29 @@ def tick args
   args.outputs.solids  << Square.new(10, 10, 32)
 end
 </pre>
+<h1 id='--docs---gtk--outputs#borders-'><code>GTK::Outputs#borders</code></h1>
+<p>
+Add primitives to this collection to render an unfilled solid to the screen. Take a look at the documentation for Outputs#solids.
+</p>
+<p>
+The only difference between the two primitives is where they are added.
+</p>
+<p>
+Instead of using <code>args.outputs.solids</code>:
+</p>
+<pre>def tick args
+  #                         X    Y  WIDTH  HEIGHT
+  args.outputs.solids << [100, 100,   160,     90]
+end
+</pre>
+<p>
+You have to use <code>args.outputs.borders</code>:
+</p>
+<pre>def tick args
+  #                           X    Y  WIDTH  HEIGHT
+  args.outputs.borders << [100, 100,   160,     90]
+end
+</pre>
 <h1 id='--docs---gtk--mouse-'><code>GTK::Mouse</code></h1>
 <p>
 The mouse is accessible via <code>args.inputs.mouse</code>:
@@ -1420,6 +1423,135 @@ Example using named parameters:
   ]
 end
 </pre>
+<h1 id='--docs---numeric#elapsed_time-'><code>Numeric#elapsed_time</code></h1>
+<p>
+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`.
+</p>
+<p>
+Here is an example of how elapsed_time can be used.
+</p>
+<pre>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
+</pre>
+<p>
+And here is an example where the override parameter is passed in:
+</p>
+<pre>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
+</pre>
+<h1 id='--docs---numeric#elapsed?-'><code>Numeric#elapsed?</code></h1>
+<p>
+Returns true if <code>Numeric#elapsed_time</code> is greater than the number. An optional parameter can be passed into <code>elapsed?</code> which is added to the number before evaluating whether <code>elapsed?</code> is true.
+</p>
+<p>
+Example usage (no optional parameter):
+</p>
+<pre>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
+</pre>
+<p>
+Example usage (with optional parameter):
+</p>
+<pre>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
+</pre>
+<h1 id='--docs---numeric#created?-'><code>Numeric#created?</code></h1>
+<p>
+Returns true if <code>Numeric#elapsed_time == 0</code>. Essentially communicating that number is equal to the current frame.
+</p>
+<p>
+Example usage:
+</p>
+<pre>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
+</pre>
 <h1 id='--docs---kernel-'><code>Kernel</code></h1>
 <p>
 Kernel in the DragonRuby Runtime has patches for how standard out is handled and also contains a unit of time in games called a tick.