demiurge 0.2.0

data/RELOADING.md

@@ -0,0 +1,94 @@
+# Reloading, Debugging and Demiurge Engines
+
+Demiurge tries to make it easy to reload World Files in
+development. What's so complicated about that?
+
+Where possible, Demiurge tries to just keep the same zones, locations,
+agents and so on with the same action names. If you change the code
+for something that already exists, great! Demiurge can easily put that
+together and give you the new code.
+
+Fabulous. All done, right?
+
+Nope. What if you rename a zone? You probably don't *want* Demiurge to
+try to guess that based on the line in the file, or the new name. If
+it gets it right 60% of the time (which is optimistic)... Well, what
+about the other 40%? Also, you won't be in the habit of noticing and
+fixing it, which will occasionally be *really* bad.
+
+So: expect this to be okay for development. Do *not* expect it to work
+perfectly, nor for you to be able to test a bunch of development
+changes with incremental reloads and then have it work perfectly in
+production later.
+
+State is hard. Reloading is hard. Demiurge has some ways to help a
+little. But this is all still hard.
+
+## Resetting
+
+## Simple Best Practices
+
+When Demiurge loads your World Files, it has to execute them as Ruby
+code. That means if you do something as a side effect (print to
+console, write a file) it gets done every time. So try not to do that.
+
+## What Makes This Easier?
+
+Players love big persistent games like Minecraft where everything they
+do persists forever and they can make huge changes to the game. And
+yet there are very few games like that. Why?
+
+Partly because it's really, really hard to *test* changes to a world
+like that. Wouldn't it be cool if you could add new lava-or-water-type
+blocks to Minecraft and change how they worked? Maybe you could make
+some kind of slime-or-pudding block that poured and flowed like that?
+And then make pudding sculptures, like those wonderful towers or
+fortresses you make with water or lava pouring over them in Minecraft
+Creative Mode? Now, think about how you'd *test* those changes in a
+big persistent Minecraft-type world where everybody was building stuff
+all the time.
+
+(For the same reason, a Minecraft MMO would be a *gigantic* pain to
+create. Just sayin'.)
+
+If you were making changes to how the pudding blocks worked, you'd
+have players *howling* every time the flow changed and their
+fortresses looked different. You can't just put that out there and
+then mess with it -- the "mess with it" part is really hard in a big
+persistent world. Players get really attached to every small change.
+
+So what do you do? Well, one thing is to wipe the slate clean,
+regularly. Minecraft doesn't guarantee that you know exactly where
+every skeleton or creeper is, and mostly you don't expect to. Most
+games are even more like that -- World of Warcraft knows where
+monsters *spawn* and it knows their *routes*, but you don't expect to
+come back an hour later and see anything you did persist. Dropped
+items disappear, killed monsters come back.
+
+By having a lot of non-persisted state (information the game is
+allowed to wipe clean), you leave room for making changes. If an admin
+messes around with exactly how monsters spawn (how many? what timing?
+do they roam around a little? where?) that doesn't feel like a big
+deal -- you're used to that information getting reset constantly, and
+little changes to it feel like window dressing. You forgot exactly
+which monsters you killed thirty seconds after you killed them because
+you don't *expect* that to be useful to remember. The spawn points
+might be important - especially if you're used to sneaking past them
+or quietly taking a route that keeps you out of the way of the big
+nasties. But even changing those spawn points feels "fair" - it's
+different from losing track of, say, how much gold your character
+currently has, or exactly which blocks you put where in Minecraft to
+make a shelter.
+
+In general, you should make it clear when there's information you
+won't be persisting. If you need to wipe out dropped weapons on the
+floor (you probably do) then start that decay process *early* - you
+want folks to know it's possible so that it's not a horrible surprise
+when it happens.
+
+And you want to persist as little information as you can get away
+with. Any part of the game world that you (the admin) are allowed to
+play with or reset is information you don't need to keep intact as
+precious player data.
+
+

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/SECURITY.md

@@ -0,0 +1,103 @@
+# Security and User-Supplied Code
+
+Demiurge is designed for an environment with very high-privilege code
+(e.g. Demiurge itself, framework code, setup code) and somewhat
+lower-privilege code (e.g. world files, certain player actions,
+display code like particles.) It is *not* designed to let you just
+"drop in" untrusted code and expect everything will be fine, basically
+ever.
+
+## Sandboxing
+
+In general, "sandboxing" code to prevent it from doing things you
+don't want is very hard. Ruby does nothing to make this easier - only
+a few languages are easy to "sandbox", with JavaScript being by far
+the most advanced in that specific respect -- it's designed to run in
+the browser environment in a very specifically sandboxed way.
+
+There are a few Ruby sandbox implementations (the current leader seems
+to be [JRuby Sandbox]("https://github.com/jwo/jruby-sandbox")), but
+in general they're hard to get right. Proving that a particular Ruby
+snippet can't access a particular class (say ObjectSpace, which gives
+full access to 100% of everything, or any flavor of "eval," or
+"binding," or...) is very, very hard.
+
+So: the current Demiurge codebase makes a much simpler assumption:
+there are two overall flavors of code and neither is safe.
+
+The first flavor is administrative code. Anything that runs with full
+privilege (actions marked as full-privilege, anything in a framework
+file or other non-World dot-rb file) must be examined very
+carefully. These are full-danger code that can do absolutely anything,
+and you must trust such code as much as the code you wrote for
+yourself. They can do anything you can do, and running them "just for
+this one person" without fully examining them is a terrible, terrible
+idea.
+
+## World Code
+
+The second flavor is world code. Non-administrative zones, actions for
+locations and agents and other similar code is world code. It runs
+with more restrictions. It doesn't have methods to directly call most
+dangerous operations like reloading your world from a state dump or
+reloading a zone. You still have to examine it - a creative Ruby coder
+can potentially get at just about anything they want to. But the basic
+operations it provides are less dangerous, and a very simple chunk of
+world code will normally not be able to do anything *too* awful.
+
+However, the
+[Halting Problem](https://en.wikipedia.org/wiki/Halting_problem)
+guarantees that we can't make many guarantees about what code does,
+and we certainly can't be sure it returns in a crisp, predictable
+manner in general. So: assume that even world code, even very simple
+world code, can cause you significant problems.
+
+## Special Cases
+
+There are very restricted cases where you can be sure that everything
+is fine. As an intentionally-silly example, if you let the player
+supply a six-digit hexadecimal color value and then apply it to be the
+color of something using CSS... That's pretty darn securable. If you
+want to make that safe, you totally can.
+
+And as an intermediate-difficulty thing, it's not hard to come up with
+a definition language for things like particle effects that only have
+a few operations, limited conditionals and no loops, which are
+essentially safe. At most a bad world-builder might be able to slow
+down people's browsers, which isn't a huge deal.
+
+But in general, if a language is [Turing Complete](https://en.wikipedia.org/wiki/Turing_completeness) then there's a way
+to make it misbehave in a way you can't automatically detect. Which
+means any language interesting enough to build a world in is also
+interesting enough to cause you lots of problems with securing it
+automatically.
+
+It's still not a bad idea to build special cases. Those are where
+you'll be able to let *players* supply content without carefully
+vetting it. If you need world-builders to write zones in Ruby then you
+need to have somebody review the code manually - there's not going to
+be an enforcement system that's good enough to catch all the
+problems. But if you want players to color their own gear or even make
+up their own custom particle effects, that's probably not a problem.
+
+It's surprising how much you can do with a special-purpose language or
+format for just a few specific things. CSS in your browser is an
+example of how far you can take this idea, though these days CSS is
+Turing Complete too...
+
+## How Do We Do It Right?
+
+There is an eventual solution that could help this a fair bit, at a
+cost of performance and complexity. By running a separate Ruby process
+with limited privilege, it could become possible to halt a runaway
+chunk of world code and watch its operations more carefully - it's
+always easier to monitor a chunk of Ruby code from *outside* that Ruby
+process.
+
+That gets around problems with the various sandbox libraries -- how do
+you avoid them using 100% CPU and never returning? How do you get
+around them allocating unlimited memory? These aren't problems you can
+get around with a Ruby-space sandbox library, not really. You need to
+run the code evaluation in a separate process so that you can limit
+those things without putting your limiting code in the same Ruby
+interpreter, where "bad actor" code can get at it.

data/WORLD_FILES.md

@@ -0,0 +1,134 @@
+# Demiurge World Files
+
+Demiurge includes a very convenient Ruby DSL (Domain-Specific
+Language) for declaring your zones, locations, agents and so on. These
+are referred to as World Files, and are by far the easiest and most
+common way to create a simulation using Demiurge.
+
+Unfortunately, the Builder classes in the API documentation aren't a
+great way to document the World File syntax and how to use it. There
+are some good examples, but many of them are either too complicated,
+or intentionally weird. For instance, the test/ directory is full of
+World File examples that are designed to test weird corner cases or
+generate errors or both.
+
+This is a quick guide to using World Files. It's not full and
+comprehensive. But it may provide a kick-start, after which the
+Builder classes won't seem quite so bizarre and inscrutable.
+
+Normally World Files are stored in a directory in your game. I like
+calling it "world". If you used multiple Demiurge engines for some
+reason, you'd probably want to store their two sets of World Files in
+two different directories.  But for a single Engine, you'd normally
+want a single directory of World Files.
+
+## Getting Started
+
+Your game will need to load its World Files somehow. Here's a good
+simple example of how to do that:
+
+    Dir["**/world/extensions/**/*.rb"].each do |ruby_ext|
+      require_relative ruby_ext
+    end
+    @engine = Demiurge.engine_from_dsl_files *Dir["world/*.rb"]
+
+This example doesn't try to do any kind of sorting to load the files
+in a particular order. In other words, you'll need to do something
+fancier if your game gets big.
+
+It also assumes that all your World Files are in the top-level
+directory, which won't stay true for long either. So: you can start
+with this example, but you'll need to change it later.
+
+## Your First Zone
+
+Here's an example file containing a very simple zone for use with
+Demiurge-CreateJS:
+
+    zone "trackless island", "type" => "TmxZone" do
+      tmx_location "start location" do
+        manasource_tile_layout "tmx/trackless_island_main.tmx"
+        description "A Mysterious Island"
+      end
+    end
+
+If you're using Demiurge-CreateJS (aka DCJS) then you'll probably want
+to use 2D tile-based locations, also called TmxLocations. Those are
+the ones you can generate using the Tiled map editor. See
+Demiurge-CreateJS for more details.
+
+If you're using Demiurge on your own projects without DCJS, you can do
+that too. Here's an example administrative zone containing a player
+definition:
+
+    # Player information can be stored here. In general, if you want
+    # information to stick around it needs a StateItem.  An "inert"
+    # StateItem just means it doesn't change on its own or take any
+    # actions.
+    inert "players"
+    
+    zone "adminzone" do
+      agent "player template" do
+        # No position or location, so it's instantiable.
+    
+        # Special action that gets performed on character creation
+        define_action("create", "engine_code" => true) do
+          if ["bob", "angelbob", "noah"].include?(item.name)
+            item.state["admin"] = true
+          end
+        end
+    
+        define_action("statedump", "tags" => ["admin", "player_action"]) do
+          dump_state
+        end
+      end
+    end
+
+You can create interesting object interactions with actions. You can
+see a few actions above, but they're just the tip of the iceberg.
+Here's a fun example where an agent can kick some stones down a cliff
+and they'll start a mini-avalanche. The bigger the initial kick, the
+bigger (by far) the total number of stones falling down:
+
+    zone "echoing cliffs" do
+      location "cliffside" do
+
+        agent "stone kicker" do
+          define_action "kick stones" do |how_many|
+            notification type: "echoing noise", "stone size": how_many, location: item.location_name
+            how_many -= 1
+            if how_many > 0
+              action "kick stones", how_many
+              action "kick stones", how_many
+            end
+          end
+        end
+      end
+    end
+
+Each action block (the do/end part) is just Ruby code, so you can do
+whatever Ruby can do there. The hard part is just figuring out what
+information you can work with, and what you're allowed to do with
+it. The methods above called "notification", "action" and "dump_state"
+above are all standard and can be found in the BlockRunner classes -
+that's AgentBlockRunner, ActionItemBlockRunner and EngineBlockRunner,
+depending on how you run it. Agents get the AgentBlockRunner,
+ActionItems get the ActionItemBlockRunner, and you only get the
+EngineBlockRunner if you specifically pass the ":engine_code" option
+to your action.
+
+## Security
+
+There's a SECURITY guide in its own file. But the short version is:
+keep in mind that World Files are *not* secure. You should read
+through any World File that somebody else gives you completely before
+you add it to your game. A bad World File can steal your in-game
+passwords and code. It can even attack other programs running on the
+same server as your game (which might be your home computer, where you
+do your banking.) It can send somebody else your data, and it can
+download other code from the Internet if it's connected to the
+Internet.
+
+Do *not* accept unknown World Files from other people. It's like
+running a downloaded .EXE on a Windows machine - it can do whatever
+your computer can, and you really shouldn't let it.

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "demiurge"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/demiurge.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'demiurge/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "demiurge"
+  spec.version       = Demiurge::VERSION
+  spec.authors       = ["Noah Gibbs"]
+  spec.email         = ["the.codefolio.guy@gmail.com"]
+
+  spec.summary       = %q{A creator and manager for game rules and state.}
+  spec.description   = %q{A creator and manager for game rules and state, separate from displaying and controlling the game. The idea is that a primarily-simulation game may be written using Ruby rules and a connection to the Demiurge process, while control and display are handled separately. This approach is primarily useful for 'simulation' games rather than fast-reflex 'twitch' games.}
+  spec.homepage      = "https://github.com/noahgibbs/demiurge"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "multi_json", "~>1.12"
+  spec.add_runtime_dependency "tmx", "~>0.1.5"
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

data/exe/demirun

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby -w -I./lib
+
+require "demiurge"
+require "demiurge/dsl"
+require "demiurge/tmx"
+
+require "multi_json"
+
+if ARGV.size < 1
+  raise "Please give at least one Demiurge DSL file to parse!"
+end
+
+engine = Demiurge.engine_from_dsl_files(*ARGV)
+engine.finished_init
+
+loop { engine.advance_one_tick }