ajuc / pefjs Goto Github PK

Process Engine For Java Script (pefjs)
    
Copyright 2012 Sebastian "Ajuć" Pidek
You can mail to me: ajuc00 on google email service.

CREDITS.

This project is inspired by jbpm ( http://www.jboss.org/jbpm ), but is intended to be much simpler and less enterprisey :). I plan to avoid XML.
Also there's no business in name, because intended use is engine for quest and dialog graphs in game I'm currently working on.   

ELEVATOR PITCH

This is a simple, extensible engine that makes it possible to run graphs specified with jsDot graphical graph editor (with some extensions).
Processes are specified in format borrowed from jsDot and extended a little (but fully compatible with jsDot ( http://code.google.com/p/jsdot/ )). It's just JSON. Engine supports multiple execution tokens in one process instance and forking (and will support joining).
Actions can be specified for each node, and actions work on provided externalState argument - you can pass anything there and process will run actions on it.     

OVERVIEW

Basic idea is - we have graph with nodes and edges. Nodes specify actions and waiting points in our process, edges specify possible transitions between nodes. So I'll call edges "transitions".
Also we can have conditions on transitions, so we wait in node A until some condition on some transition towards any other node is true, at which point we move to node B.

I'll call this graph a "process definition". Yes, it's shameless theft from jbpm terminology. Anyway.

We can take such process definition, and start process instance based on it. Process instance is just one execution of process specified by given process definition.
Process instance is basicly set of tokens.

Token is marker of point of the execution of given process. At any given time each token must be at some node in process definition. At the begining token is in the start node.
Then process engine is "pushed" from outside by some thing, and it propagates token throught transitions to next nodes.

There can be many tokens in a process definitions at once, because I needed to support situation like this: player needs to talk with person A and person B to finish
a quest, but order of these talks is unimportant. So I specify a graph like this:

(start) -> (fork)
(fork) - [condition: talked with A] -> (A [action: show notification to player]) 
(fork) - [condition: talked with B] -> (B [action: show notification to player])
(A) -> (join wait for all)
(B) -> (join wait for all)
(join wait for all) -> (quest finished [action: player levels up])

//TODO - join nodes are not implemented yet.
//TODO - put images of graphs from jsDot here

ARCHITECTURE

//TOCOMMENT

EDITOR

I use JSON data fromat compatible with (or stolen from :) ) jsDot graph editor ( http://code.google.com/p/jsdot/ ), so it's possible and recommended to use jsDot to specify your process definitions.
I had to extend jsDot a little to allow arbitrary data to be edited, I'll publish my version of jsDot shortly, I just need to clean it up a little.

NODE TYPES
	
	start - at the start of process instance in each start node token appears. Can't be also a join.
	fork - when token is there, in next propagation token "forks" into as many tokens, as there is outgoing transitions, and one copy of the token moves throught each of the transitions at once. Original token is destroyed. There CANNOT be conditions on outgoing transitions.
	join - when token comes here, it waits until as many other tokens come, as there is incoming transitions. When this happens - tokens merge into a new token, and moves thorught outgoing transitions. There CANNOT be conditions on outgoing transition.
	kill - when token comes here, it is destroyed in next propagation. 

TESTS

I included tests suite in tests.html. Not complete coverage, but most features are touched by some tests.

EXAMPLES

I need to put some examples here.