git.r.bdr.sh - rbdr/serpentity/blob - README.md

   1 # Serpentity
   2
   3 Serpentity is a simple entity framework inspired by [Ash][ash].
   4
   5 Usage:
   6
   7     require('serpentity');
   8
   9 ## Instantiating an engine
  10
  11     var engine = Serpentity();
  12
  13 Add entities or systems, systems are added with a priority (the smaller
  14 the number, the earlier it will be called):
  15
  16     engine.addEntity(entityFactory());
  17     engine.addSystem(new GameSystem(), priority);
  18
  19 Update all systems:
  20
  21     engine.update(dt);
  22
  23 Remove entities or systems:
  24
  25     engine.removeEntity(entityReference);
  26     engine.removeSystem(systemReference);
  27
  28 ## Creating Entities
  29
  30 Entities are the basic object of Serpentity, and they do nothing.
  31
  32     var entity = new Serpentity.Entity();
  33
  34 All the behavior is added through components
  35
  36 ## Creating Components
  37
  38 Components define data that we can add to an entity. This data will
  39 eventually be consumed by "Systems"
  40
  41     Class("PositionComponent").inherits(Serpentity.Component)({
  42         prototype : {
  43             x : 0,
  44             y : 0
  45         }
  46     });
  47
  48 You can add components to entities by using the add method:
  49
  50     entity.add(new PositionComponent());
  51
  52
  53 Systems can refer to entities by requesting nodes.
  54
  55 ## Working with Nodes
  56
  57 Nodes are sets of components that you define, so your system can require
  58 entities that always follow the API defined in the node.
  59
  60     Class("MovementNode").inherits(Serpentity.Node)({
  61         types : {
  62             position : PositionComponent,
  63             motion : MotionComponent
  64         }
  65     });
  66
  67 You can then request an array of all the nodes representing entities
  68 that comply with that API
  69
  70     engine.getNodes(MovementNode);
  71
  72 ## Creating Systems
  73
  74 Systems are called on every update, and they use components through nodes.
  75
  76     Class("TestSystem").inherits(Serpentity.System)({
  77         prototype : {
  78             added : function added(engine){
  79                 this.nodeList = engine.getNodes(MovementNode);
  80             },
  81             removed : function removed(engine){
  82                 this.nodeList = undefined;
  83             }
  84             update : function update(dt){
  85                 this.nodeList.forEach(function (node) {
  86                     console.log("Current position is: " + node.position.x + "," + node.position.y);
  87                 });
  88             }
  89         }
  90     });
  91
  92 ## That's it
  93
  94 Just run `engine.update(dt)` in your game loop :D
  95
  96 ## Checking it in the frontend (dev).
  97
  98 You can link the bower package (bower.json is in `lib/serpentity/` to
  99 make paths cleaner), then link it again from the root directory and
 100 spawn a python server (`python -m SimpleHTTPServer`). The test page
 101 will be available in `http://localhost:8000/browser_test/`
 102
 103 If you just want to use it, it's available as a bower package!
 104
 105
 106 ## TO-DO
 107
 108 * Removing components
 109 * Implement the ashteroids demo (Serpentoids)
 110 * Actually check performance
 111
 112 [ash]: http://www.ashframework.org/