1 files changed, 120 insertions, 0 deletions
diff --git a/Data/BuiltIn/Libraries/coil/README.md b/Data/BuiltIn/Libraries/coil/README.md
new file mode 100644
index 0000000..bec60a0
--- /dev/null
+++ b/Data/BuiltIn/Libraries/coil/README.md
@@ -0,0 +1,120 @@
+# coil
+A tiny cooperative threading module for Lua. Coil is based around coroutines,
+allowing many cooperative threads to run simultaneously.
+
+## Usage
+The [coil.lua](coil.lua) file should be dropped into an existing project and
+required by it.
+```lua
+coil = require "coil"
+```
+At the start of each frame `coil.update()` should be called and given the delta
+time since the last call as its argument.
+```lua
+coil.update(deltatime)
+```
+Coil refers to each cooperative thread as a *task*; new tasks can be created by
+using the `coil.add()` function.
+```lua
+-- prints the word "hello" each second for 5 seconds
+coil.add(function()
+  for i = 1, 5 do
+    print("hello")
+    coil.wait(1)
+  end
+end)
+```
+
+### coil.wait()
+As tasks are cooperative, they must be manually yielded to allow other parts of
+the program to continue. This is done by calling the `coil.wait()` function.
+The function can be used to wait for different events before continuing.
+
+* If wait is called with a number as its argument then it waits for that number
+  of seconds before resuming.
+* If wait is called with a callback created by coil.callback() it will wait
+  until that callback function is called before resuming; it will return the
+  arguments passed to the callback when it was called.
+* If wait is called with no arguments it waits until the next frame
+  (`coil.update()` call) before resuming; it returns the time that has passed
+  since the last frame.
+
+### coil.callback()
+The `coil.callback()` function can be used to create a special callback which,
+if passed to the `coil.wait()` function, will cause the task to wait until the
+callback is called.
+```lua
+-- Prints "Hello world" when `cb()` is called.
+coil.add(function()
+  cb = coil.callback()
+  coil.wait(cb)
+  print("Hello world")
+end)
+```
+
+### coil.update(dt)
+This should be called at the start of each frame. Updates all the tasks,
+running those which aren't waiting or paused. `dt` should be the amount of time
+in seconds which has passed since the function was last called.
+
+### coil.add(fn)
+Adds a new task, the task will begin running on the next call to
+`coil.update()`.
+```lua
+-- prints "hello world" every 2 seconds
+coil.add(function()
+  while 1 do
+    print("hello world")
+    coil.wait(2)
+  end
+end)
+```
+
+## Stopping a task
+A task can be stopped and removed at any point by calling its `:stop()` method.
+To do this the task must be assigned to a variable when it is created.
+```lua
+-- Adds a new task
+local t = coil.add(function()
+  coil.wait(1)
+  print("hello")
+end)
+
+-- Removes the task before it has a chance to run
+t:stop()
+```
+
+## Groups
+Coil provides the ability to create task groups; these are objects which can
+have tasks added to them, and which are in charge of updating and handling
+their contained tasks. A group is created by calling the `coil.group()`
+function.
+```lua
+local group = coil.group()
+```
+
+Once a group is created it acts independently of the `coil` object, and must
+be updated each frame using its own update method.
+```lua
+group:update(deltatime)
+```
+
+To add a task to a group, the group's `add()` method should be used.
+```lua
+group:add(function()
+  coil.wait(10)
+  print("10 seconds have passed")
+end)
+```
+
+A good example of where groups are useful is for games where you may have a set
+of tasks which effect objects in the game world and which you want to pause
+when the game is paused.  A group's tasks can be paused by simply neglecting
+to call its `update()` method; when a group is destroyed its tasks are also
+destroyed.
+
+
+## License
+This library is free software; you can redistribute it and/or modify it under
+the terms of the MIT license. See [LICENSE](LICENSE) for details.
+