demiurge 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 16771a3630ea74f9412194ba68ec9ebc5181380c
+  data.tar.gz: 7bd716fe644a7be1e32bd49ab0d39d4cc66a0e97
+SHA512:
+  metadata.gz: b10caf567ea6f50864c594e22ac16708407e325ec72a543ec403a7439ede2c512c82f6bb383dc019ba343cd71dbd131fdc87b99a4a5108be7e3c7dc2fd6bac62
+  data.tar.gz: 4ec6595a79d26d53fb40c04725820239b434195b3979583f589a0615d07339cf104680b62cb5669bdb3851b2588f560a9d7b3f39a3fa6f97d152eac4a33c6226

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.14.6

data/.yardopts

@@ -0,0 +1,5 @@
+--readme README.md
+--title 'Demiurge API Documentation'
+--charset utf-8
+--markup markdown
+'lib/**/*.rb' - '*.md'

data/AUTHORS.txt

@@ -0,0 +1,6 @@
+The core Demiurge engine tries to use only CC0-licensed content -- in
+effect, public domain. But it's nice to credit people when they make
+things for you. In that spirit:
+
+Thanks to Jurkan, author of collision.png, a simple CC0-licensed collision-layer tileset.
+Thanks to Hyptosis of lorestrome.com for CC0-licensed content including portraits and MageCity tilesets.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at the.codefolio.guy@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/CONCEPTS.md

@@ -0,0 +1,271 @@
+# Demiurge Simulated Worlds
+
+Demiurge is a great way to prototype and develop an interesting
+simulated world. It's intended to be flexible, powerful and easy to
+tie into other systems.
+
+Let's talk about the components of a Demiurge world and what they do.
+
+## Engines, State, Ticks
+
+A single Demiurge simulation is called an Engine. It can be loaded
+from World Files and state.
+
+World Files determine the behavior of the world - what kinds of
+entities does the world contain? How do they act? What are the rules
+of physics that define that world?
+
+State determines the current situation of that world. If your world
+physics allows any number of rabbits in a particular field, how many
+are there right now and where are they?
+
+A single step of simulation is called a "tick", like the ticking of a
+clock.
+
+The world "entity" for a thing in the world is fairly vague. It may
+refer to an "item", a "creature", an "area" (another vague word) or
+something else. An entity is "a thing or things in the world" rather
+than one specific abstraction that Demiurge defines. Entities
+generally can act and be acted on, can pick things up and be picked
+up, can take place in a location or be that location. In general, a
+single individual entity will only do a few of those things, though.
+
+## Intentions, Actions and Events
+
+A world may contain unchanging things, usually represented as
+rules. It may contain changeable and movable items. And it may contain
+items or creatures that act on their own. Demiurge can distinguish
+between these categories, but it usually does so by distinguishing
+between "rules" and "state" rather than between "intelligent" and
+"unintelligent." Intelligence is mostly a matter of how complex the
+rules are, and what objects they tend to affect.
+
+A Demiurge Engine normally moves forward in discrete steps. The
+current state is examined to create a list of Intentions, which do not
+(yet) change state. The Intentions are then resolved into
+notifications and state changes. One full state/intention/event cycle
+is a tick.
+
+Demiurge doesn't require that ticks occur at particular times
+according to a real-world clock. You might choose to create entities
+and rules that care about a real-world clock, but Demiurge doesn't
+care. Ticks can be evenly spaced or not, as long as your entities'
+rules reflect that.
+
+## State Items, and the Difference Between Rules and State
+
+Rules exist entirely within World Files and the Demiurge framework
+itself. The effects of rules can change according to current state,
+but the rules themselves are in the World Files and do not depend on
+state.
+
+State in Demiurge must be serializable as JSON. That gives a
+combination of numbers, strings, true/false/undefined special values,
+lists and objects (dictionaries/hashes) as the set of all state
+data. Each State Item gets a chunk of state and manages its own
+rules. Each State Item's item name must be unique. There may be lots
+of a particular *kind* of state item, but each one gets its own unique
+name and its own chunk of state.
+
+A "State Item" applies rules to state. As a programmatic object, it
+can apply its rules (which are fixed) to its state (which can change
+at any time).
+
+This abstraction makes it easy to consider hypotheticals -- to ask,
+"if the state were different in this way, how would that change the
+world?"
+
+## Item Naming and Instances
+
+A Demiurge entity (including Zones, Locations, Agents and many others)
+must have a single, fully unique name within a given Engine. In World
+Files, normally a human has to declare the name and that name needs to
+be unique.
+
+Names have a few restrictions. You can use alphanumeric characters
+(letters and numbers, including Unicode letters and numbers) along
+with spaces, dashes and underscores in the names. But other
+punctuation including quotes, hash signs, dollar signs and so on
+aren't permitted. These names are used internally as unique
+identifiers and you don't need to worry about showing them to humans,
+so don't worry about not being able to put punctuation you care about
+in the names. The names are case-sensitive -- that is, "Bobo" and
+"boBo" are completely different items because an upper-case and
+lower-case letter count as different from each other.
+
+Certain items, such as Zones in World Files may be reopened by
+declaring another item (e.g. another Zone) with the same name. But if
+so, they aren't two different Zones with the same name. Instead, the
+files declare a single Zone across multiple files. That's perfectly
+legal, just as you may declare a room in one World File while
+declaring creatures and items inside it in another World File. But
+it's all a single room, even if it's declared in multiple places for
+human convenience. If you're used to programming with Ruby classes,
+this idea of "reopening" the same zone in a new file will probably
+seem very familiar.
+
+Sometimes you want to declare an object and then have a lot of
+them. Something like a wooden spoon, a low-level slime monster or a
+player body object may get just one declaration in the World Files for
+a lot of individual objects in the world. Differences in state or
+appearance can add variation where you need it without requiring
+giant, bloated World Files with fifteen identical slime monsters that
+just have a "7" or a "12" after their name.
+
+There are a few kinds of special punctuation in names and name-like
+things that Demiurge may use for itself. For instance, a Position (see
+later in this file) is a location's item name followed by a pound sign
+and then some additional information, such as
+"my\_room#25,71". Certain special objects and other things in Demiurge
+can use other punctuation (e.g. colon or dollar-sign), but these
+shouldn't occur in human-named objects in World Files.
+
+## Events and State Changes
+
+Often an Intention turns into a change of state. For example, an item
+is picked up, or a person moves from one location to another. When
+that occurs, there may also be one or more notifications. The state
+change is what it sounds like - if a person moves from one place to
+another, their "location" is part of their state, and it's different
+after the tick than it was before.
+
+A Notification doesn't necessarily involve a change of state, though
+the two will often happen together. The Notification doesn't cause the
+state change, though it may be the result of one. A Notification is
+simply a discrete that can be perceived in the world. A continuous,
+ongoing event is state, not a Notification, though if it begins, ends
+or changes significantly it may *cause* a Notification.
+
+If a person moves from one room to another, their location changes and
+so their state changes. There is also likely to be a Notification
+associated with it - a detectable, trackable event which can be
+watched for by other reactive entities in the world.
+
+A Notification doesn't have to involve a state change, though. For
+instance, if a character looks around shiftily or grins momentarily,
+that doesn't necessarily change any recorded part of their state. But
+another character may watch for the Notification and if they detect
+it, they may react to it.
+
+## The Cycle of a Tick
+
+Initially, the state is effectively frozen - nothing should change
+it. It may be literally kept immutable in the program, depending on
+required efficiency.
+
+For each tick, code runs to generate Intentions on the part of any
+entities that can act. Anything that will change state or create a
+Notification requires an Intention.
+
+Then, in some order of precedence, these Intentions are resolved one
+at a time.
+
+First an Intention is "validated" - can it happen at all? If not, it
+is discarded as impossible, undesirable or otherwise "not going to
+happen" with no effects of any kind.
+
+At this point, the state becomes changeable again. This may involve
+unfreezing or copying.
+
+Then an Intention is offered - other entities may attempt to block,
+modify or otherwise interfere with what occurs. This may result in the
+Intention being blocked as in the validation stage (another entity
+effectively makes its result impossible, resulting in nothing
+happening) or its effects may be modified and/or other effects may
+immediately occur as a result.
+
+As that process resolves, the Intention may modify state. It may also
+send Notifications. In general, a Notification reflects a completed
+operation and the receiver can only react, not change or block the
+action. While a Notification allows the receiver to modify state, that
+receiver should only modify its own state or send additional
+Notifications - it should not take "instant reactions", which should
+be resolved in the offer/modify/veto stage.
+
+After all these Notifications have resolved, including any
+Notifications raised in response to other Notifications, the tick
+begins again with the new state, which may be frozen during the early
+Intention phases.
+
+## Zones, Location and Position
+
+Location in Demiurge starts with the Zone. A Zone is a top-level
+entity that manages state and flow of execution roughly independently
+of other zones.
+
+Different Zones may have very different "physics" between them - a
+Zone might be entirely text descriptions, while a different Zone is
+managed entirely in 2D tile graphics, for instance and a third Zone
+could be an HTML UI. It's possible to do that within a single Zone in
+some cases, if the Zone's "physics" permit it, but such changes are
+expected between Zones.
+
+A Location within a Zone may have some difference, but needs to
+cooperate effectively with the Zone and with other Locations
+inside. In a 2D tile-based Zone, it may be important that Zone
+pathfinding works across multiple Locations, for instance. In a
+text-based Zone of mostly-independent locations, there may be a
+notification system that allows events in adjacent rooms to be visible
+in certain other rooms as text notifications.
+
+In general, a Zone defines the top-level "physics" and the nature of
+space and location within itself, and Locations coordinate to make
+that happen. Technically Locations are optional - it's possible for a
+Zone to skip Locations entirely. But ordinarily there is some form of
+subdivision.
+
+Locations are also allowed to contain other Locations, and may do so
+or not depending on the nature of their Zone.
+
+When one asks for an entity's "location", one may mean "what entity
+inside a Zone is it contained in?" However, there is not always a
+well-defined answer to that question. For instance, an "infinite
+space" Zone with no sub-locations that handles all object interactions
+directly may not have "Location" sub-objects within itself at
+all. What "location" is somebody at within the Zone? The Demiurge
+entity in question is just the Zone, since there are no smaller
+Location entities within it.
+
+And within a Location, an entity may occupy different positions. In a
+box of 3D space or a 2D tile map or a MUD-style room with objects
+inside, a given entity may be at "x: 27.4, y:-1547.2, z: 297.0" or "x:
+27, y: 5" or "next to the gray lamp."
+
+The Demiurge class "Demiurge::Location" is basically advisory -
+locations within a Zone aren't required to belong to that class, may
+be part of a tree of different location objects or may not exist at
+all.
+
+As a result, a "location" in Demiurge is about author intention, not
+really about what Demiurge does with the object in question. The Zone
+defines what being a location means, and it may vary widely from Zone
+to Zone.
+
+But then, how does one specify? With a Position.
+
+A Position is given relative to a Zone or an object inside the Zone,
+such as a Location (if one exists.) It is of the form
+"item\_name#coordinates" where "item\_name" is a canonical
+Demiurge item name, instanced or non-instanced. The coordinates may be
+in a form appropriate to their zone such as "7,25" or
+"29.45/81.6/Kappa" or "left\_of/gray\_greasy\_lamp". The coordinates
+should not contain a pound-sign, a dollar sign or other characters
+that aren't legal in a Demiurge item name.
+
+## The Admin Zone and Positionless Actions
+
+Sometimes, a thing happens that doesn't belong in any specific game
+zone. A player might fail to create a new account - what zone would
+that belong in? An admin might reload the whole world, which isn't
+specific to any one zone. An error might occur that can't be traced to
+any specific zone.
+
+When that happens, a special zone name, "admin", is used. There cannot
+be an "admin" zone in a world file. Instead, "admin" is the name of an
+automatic InertStateItem which holds system information like how many
+total ticks have passed in the world, and the current notification_id
+and intention_id for queueing.
+
+Positionless occurrences like the examples above (e.g. account
+creation failures) will appear to occur in this nonexistent "admin"
+zone.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in demiurge.gemspec
+gemspec

data/HACKING.md

@@ -0,0 +1,34 @@
+# Hacking Demiurge
+
+When in doubt: read the source, tests and examples of course, just
+like any other code.
+
+## State and JSON
+
+Demiurge is architected in such a way that StateItems contain logic
+about how to manipulate state. StateItems contain current state and
+can calculate new Intentions and apply Actions.
+
+State can be serialized and swapped out at any time, so StateItems
+must be able to be disposable and replaceable. Since it's hard to
+serialize a procedure as JSON, generally StateItems define actions in
+their World Files or Ruby code, and the StateItem contains the names
+of the actions. The actual Ruby procedures are either part of the
+StateItem subclass Ruby code or they're stored as a proc in the engine
+itself.
+
+Similarly, serialized state data often contains item names rather than
+actual items. Names are easily serialized and easily handled with a
+minimum of fuss, while structures and code are both messy.
+
+## Zones and Top-Level State
+
+If every StateItem was guaranteed a call every tick, simulation would
+slow to a crawl very rapidly as the world expanded. Instead, certain
+top-level StateItems called "zones" are guaranteed to be called every
+tick and they decide how to manage the flow of execution to their
+contents.
+
+In general, a Zone manages whether to call various sub-items or
+agents, or whether to only call them sometimes, or whether to quiesce
+them completely.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Noah Gibbs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,181 @@
+# Demiurge
+
+Demiurge is an experimental game state and simulation library.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'demiurge'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install demiurge
+
+## Usage
+
+See test mini-games in the test directory. For more information, see
+lib/demiurge/engine.rb.
+
+For longer-term usage, Demiurge will normally be part of a larger
+program. Its intent is to manage behavior and state for a game or
+similar simulated world. In those cases, Demiurge will normally be
+required as a gem by its application, using normal "require
+'demiurge'"-style declarations. You can see what that looks like by
+examining test/example mini-worlds in the relevant Demiurge
+directories.
+
+If Demiurge is primarily managing a simulated world and you want to
+view the results, you'll need a display library to make its output
+visible. Currently that means Demiurge-CreateJS, which displays the
+results in your browser as a simulated world.
+
+Please note that it is very, very difficult to separate the specifics
+of behavior from the specifics of output and display - entities simply
+*behave* differently in a text-only world with generalized "locations"
+than they do in a 2D grid or a 3D world with collisions. As a result,
+even if your preferred method of output isn't as specific as "Unreal
+Engine" or "browser game" or "MUD-style text game," your simulation is
+going to have a strong "flavor" of whatever underlying physics you
+select. There is no such thing as "just plain physics, with no strong
+bias that changes the behavior of agents within it."
+
+This README doesn't tell you everything about creating and simulating
+a world with Demiurge. See CONCEPTS.md for an initial grounding in
+those ideas.
+
+## Demiurge DSL (World Files)
+
+Demiurge contains an optional Domain-Specific Language (also called a
+"DSL") which can be used to specify your simulated world and its rules
+and behaviors. The "test" directory contains some examples of these
+files.
+
+These DSLs may specify various sorts of locations and agents that roam
+them - the idea is that the world files should specify enough details
+to simulate the "world" fully, without containing too much additional
+detail on how to supply the results. Since many formats tend to pack
+this information together (e.g. TMX files contain layout and collision
+data required for simulation, but also links to image files for
+display) the Demiurge engine will often link to the display
+information without using it. This permits a display layer on top of
+Demiurge, such as Demiurge-CreateJS, to make use of the display
+information alongside the simulation data.
+
+## Specific Technologies: 2D Tile Maps
+
+Remember that "no such thing as just plain physics" bit above? As a
+consequence, Demiurge contains support for specific, non-abstract
+physics bits like "2d grid of defined terrains," also called a tilemap
+or tiled terrain.
+
+There are standards for tilemaps, such as TMX format and the Tiled map
+editor (http://mapeditor.org). TMX support also, not coincidentally,
+gives you a fairly rich source of existing media to use (e.g. The Mana
+Project and Source of Tales.) Please be careful to appropriately
+respect the licensing of this media, which requires an acknowledgement
+to the original authors for your graphics and map files.
+
+2D tile-based media is rich enough to provide interesting simulation
+and AI behaviors without being *so* interesting that your agent code
+can't be in scripting languages and spends all its time doing
+pathfinding, as would be the case with most open 3D environments.
+
+## Specific Technologies: Serializability and Immutability
+
+One of the hard challenges in game- and world-based AI is how to make
+it easy to create new content, primarily in the form of reactions and
+behavior. Those reactions and behavior are most frequently expressed
+as some form of code/scripts.
+
+Reactions and behavior can take many forms. Two common ones are called
+Intentions and Actions by Demiurge. An Intention is generated by an
+artificial intelligence based on examining its current situation. For
+instance, "I am hungry and I remember food in the next room, so I
+intend to move in that direction." An Intention will examine the state
+of the world, but will not normally change it.
+
+An Action is normally the result of an Intention, and it applies that
+intention to the simulated world. An Action will frequently change the
+state of the world, such as by moving an agent within the world, or by
+moving other non-agent items in the world (e.g. eating food, picking up a
+stick, etc.) An Action may also frequently be thwarted (e.g. an item
+is too heavy, food is not where it was suspected or remembered,
+somebody has pushed their way into the hall ahead of you and you may
+not pass.)
+
+Immutable structures provide great verifiability and terrible
+performance. The code snippets can generate a second, modified version
+of each structure, but must copy nearly the entirety of it. You may be
+certain that no old state is being modified in a sloppy way, and
+memory usage and garbage collection time are both very high.
+
+Mutable structures allow easy in-place modification for great
+performance, but they're hard to lock down when mutability isn't
+wanted (e.g. when verifying if an action is allowed to take place.)
+
+Demiurge attempts to handle this by making the code immutable per run
+of the world, and to store state data in sometimes-mutable
+JSON-serializable structures.
+
+It is assumed but only sometimes verified that when calculating
+Intentions the state of the world isn't altered. It is assumed that
+the behaviors are replicatable -- that random numbers generated from
+seeds are used in a way that is replicatable from run to run, for
+instance, or non-random behaviors reliably calculate the same
+intention from the same preconditions.
+
+This provides a compromise between full immutability (slow
+performance, great verifiability) and full mutability (fast
+performance, terrible verifiability) by switching back and forth
+between them on demand.
+
+## Development
+
+Demiurge is not yet ready for "pristine" production usage. It's not
+yet ready for you to just drop it in and use it unchanged. For that
+reason, assume you'll need to do some Demiurge development for
+yourself, whether or not you ever contribute it upstream.
+
+For more information on Demiurge's architecture, see the HACKING.md
+document in this directory.
+
+After checking out the repo, run `bin/setup` to install
+dependencies. Then, run `rake test` to run the tests. You can also run
+`bin/console` for an interactive prompt that will allow you to
+experiment.
+
+To install this gem onto your local machine, run `bundle exec rake
+install`. To release a new version, update the version number in
+`version.rb`, and then run `bundle exec rake release`, which will
+create a git tag for the version, push git commits and tags, and push
+the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/noahgibbs/demiurge. This project is intended to be
+a safe, welcoming space for collaboration, and contributors are
+expected to adhere to the
+[Contributor Covenant](http://contributor-covenant.org) code of
+conduct. See CODE\_OF\_CONDUCT.md.
+
+## References, Influences and Sources of Media
+
+* OpenGameArt and the Liberated Pixel Cup
+* Source of Tales
+* The Tiled Map Editor
+* The Mana World - https://github.com/themanaworld
+* The Mana Project
+* Evol Online
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).