Browse files

#156

Documentation
  • Loading branch information...
1 parent 4619884 commit 040f7c48ac190a6281ef31fa682e531565c56689 @sorenbs sorenbs committed Jan 8, 2012
Showing with 187 additions and 143 deletions.
  1. +19 −6 src/animation.js
  2. +137 −100 src/core.js
  3. +0 −18 src/drawing.js
  4. +1 −3 src/sound.js
  5. +30 −16 src/storage.js
View
25 src/animation.js
@@ -21,9 +21,13 @@ Crafty.c("SpriteAnimation", {
* @param y - `y` position on the sprite map. Will remain constant through the animation.
* @param toX - End `x` position on the sprite map
* @sign public this .animate(String id, Array frames)
- * @param frames - Array of containing an array with the `x` and `y` values
+ * @param id - ID of the animation reel being created
+ * @param frames - Array of arrays containing the `x` and `y` values: [[x1,y1],[x2,y2],...]
* @sign public this .animate(String id, Number duration[, Number repeatCount])
+ * @param id - ID of the animation reel to play
* @param duration - Play the animation with a duration (in frames)
+ * @param repeatCount - number of times to repeat the animation. Use -1 for infinitely
+ *
* Method to setup animation reels or play pre-made reels. Animation works by changing the sprites over
* a duration. Only works for sprites built with the Crafty.sprite methods. See the Tween component for animation of 2D properties.
*
@@ -36,13 +40,18 @@ Crafty.c("SpriteAnimation", {
*
* @example
* ~~~
- * Crafty.e("2D, DOM, SpriteAnimation")
- * .animate('name', 0, 0, 3)
- * .animate('name', 15, -1)
+ * Crafty.sprite(16, "images/sprite.png", {
+ * PlayerSprite: [0,0]
+ * });
+ *
+ * Crafty.e("2D, DOM, SpriteAnimation, PlayerSprite")
+ * .animate('PlayerRunning', 0, 0, 3) //setup animation
+ * .animate('PlayerRunning', 15, -1) // start animation
*
* ~~~
*
* @triggers AnimationEnd - When the animation finishes
+ * @see crafty.sprite
*/
animate: function(id, fromx, y, tox) {
var reel, i, tile, tileh, duration, pos;
@@ -174,10 +183,14 @@ Crafty.c("SpriteAnimation", {
/**@
* #.isPlaying
* @comp SpriteAnimation
- * @sign public Boolean .isPlaying([String reel])
- * @reel reel - Determine if this reel is playing
+ * @sign public Boolean .isPlaying([String id])
+ * @param id - Determine if the animation reel with this ID is playing
* Determines if an animation is currently playing. If a reel is passed, it will determine
* if the passed reel is playing.
+ * ~~~
+ * myEntity.isPlaying() //is any animation playing
+ * myEntity.isPlaying('PlayerRunning') //is the PlayerRunning animation playing
+ * ~~~
*/
isPlaying: function(id) {
if(!id) return !!this._interval;
View
237 src/core.js
@@ -603,7 +603,7 @@ Crafty.extend = Crafty.fn.extend = function(obj) {
* Used to extend the Crafty namespace.
*/
Crafty.extend({
- /**@
+/**@
* #Crafty.init
* @category Core
* @sign public this Crafty.init([Number width, Number height])
@@ -618,16 +618,16 @@ Crafty.extend({
* Uses `requestAnimationFrame` to sync the drawing with the browser but will default to `setInterval` if the browser does not support it.
* @see Crafty.stop
*/
- init: function(w, h) {
- Crafty.viewport.init(w,h);
-
+ init: function (w, h) {
+ Crafty.viewport.init(w, h);
+
//call all arbitrary functions attached to onload
this.trigger("Load");
this.timer.init();
-
+
return this;
},
-
+
/**@
* #Crafty.stop
* @category Core
@@ -637,13 +637,13 @@ Crafty.extend({
* To restart, use `Crafty.init()`.
* @see Crafty.init
*/
- stop: function() {
+ stop: function () {
this.timer.stop();
Crafty.stage.elem.parentNode.removeChild(Crafty.stage.elem);
-
+
return this;
},
-
+
/**@
* #Crafty.pause
* @comp Core
@@ -656,87 +656,108 @@ Crafty.extend({
* Have an entity pause the game when it is clicked.
* ~~~
* button.bind("click", function() {
- * Crafty.pause();
+ * Crafty.pause();
* });
* ~~~
*/
- pause: function(toggle) {
- if(arguments.length == 1 ? toggle : !this._paused) {
+ pause: function (toggle) {
+ if (arguments.length == 1 ? toggle : !this._paused) {
this.trigger('Pause');
this._paused = true;
-
+
Crafty.timer.stop();
Crafty.keydown = {};
} else {
this.trigger('Unpause');
this._paused = false;
-
+
Crafty.timer.init();
}
return this;
},
-
+ /**@
+ * #Crafty.timer
+ * @category Internal
+ * Handles game ticks
+ */
timer: {
prev: (+new Date),
current: (+new Date),
fps: 0,
-
- init: function() {
+
+ init: function () {
var onFrame = window.requestAnimationFrame ||
window.webkitRequestAnimationFrame ||
window.mozRequestAnimationFrame ||
window.oRequestAnimationFrame ||
window.msRequestAnimationFrame ||
null;
-
- if(onFrame) {
- tick = function() {
+
+ if (onFrame) {
+ tick = function () {
Crafty.timer.step();
- tickID = onFrame(tick);
+ tickID = onFrame(tick);
}
-
+
tick();
} else {
tick = setInterval(Crafty.timer.step, 1000 / FPS);
}
},
-
- stop: function() {
+
+ stop: function () {
Crafty.trigger("CraftyStop");
-
- if(typeof tick === "number") clearInterval(tick);
-
+
+ if (typeof tick === "number") clearInterval(tick);
+
var onFrame = window.cancelRequestAnimationFrame ||
window.webkitCancelRequestAnimationFrame ||
window.mozCancelRequestAnimationFrame ||
window.oCancelRequestAnimationFrame ||
window.msCancelRequestAnimationFrame ||
null;
-
- if(onFrame) onFrame(tickID);
+
+ if (onFrame) onFrame(tickID);
tick = null;
},
-
- step: function() {
+
+ /**@
+ * #Crafty.timer.step
+ * @comp Crafty.timer
+ * @sign public void Crafty.timer.step()
+ * Advances the game by triggering `EnterFrame` and calls `Crafty.DrawManager.draw` to update the stage.
+ */
+ step: function () {
loops = 0;
var curTime = (new Date).getTime();
- if(curTime - nextGameTick > 60 * skipTicks) {
- nextGameTick = curTime - skipTicks;
- }
- while(curTime > nextGameTick) {
- Crafty.trigger("EnterFrame", {frame: frame++});
+ if (curTime - nextGameTick > 60 * skipTicks) {
+ nextGameTick = curTime - skipTicks;
+ }
+ while (curTime > nextGameTick) {
+ Crafty.trigger("EnterFrame", { frame: frame++ });
nextGameTick += skipTicks;
loops++;
}
- if(loops) {
+ if (loops) {
Crafty.DrawManager.draw();
}
},
-
- getFPS: function() {
+ /**@
+ * #Crafty.timer.getFPS
+ * @comp Crafty.timer
+ * @sign public void Crafty.timer.getFPS()
+ * Returns the target frames per second. This is not an actual frame rate.
+ */
+ getFPS: function () {
return this.fps;
},
-
+ /**@
+ * #Crafty.timer.simulateFrames
+ * @comp Crafty.timer
+ * Advances the game state by a number of frames and draws the resulting stage at the end. Useful for tests and debugging.
+ * @sign public this Crafty.timer.simulateFrames(Number frames)
+ * @param frames - number of frames to simulate
+ */
simulateFrames: function (frames) {
while (frames-- > 0) {
Crafty.trigger("EnterFrame", { frame: frame++ });
@@ -754,49 +775,65 @@ Crafty.extend({
* @sign public Entity Crafty.e(String component1[, .., String componentN])
* @param component# - Component to add
* @triggers NewEntity
- * Creates an entity. Any arguments will be applied in the same
+ * Creates an entity. Any arguments will be applied in the same
* way `.addComponent()` is applied as a quick way to add components.
*
- * From here, any component added will augment the functionality of
- * that entity by assigning the properties and methods to that entity.
+ * Any component added will augment the functionality of
+ * the created entity by assigning the properties and methods from the component to the entity.
+ * ~~~
+ * var myEntity = Crafty.e("2D, DOM, Color");
+ * ~~~
+ * @see Crafty.c
*/
- e: function() {
+ e: function () {
var id = UID(), craft;
-
+
entities[id] = null; //register the space
entities[id] = craft = Crafty(id);
-
- if(arguments.length > 0) {
+
+ if (arguments.length > 0) {
craft.addComponent.apply(craft, arguments);
}
craft.addComponent("obj"); //every entity automatically assumes obj
-
+
Crafty.trigger("NewEntity", { id: id });
return craft;
},
-
+
/**@
* #Crafty.c
* @category Core
* @sign public void Crafty.c(String name, Object component)
* @param name - Name of the component
* @param component - Object with the components properties and methods
- * Creates a component where the first argument is the ID and the second
+ * Creates a component where the first argument is the ID and the second
* is the object that will be inherited by entities.
*
- * There is a convention for writing components. For instance properties or
- * methods that start with an underscore are considered private. A method called
- * `init` will automatically be called as soon as the component is added to
- * an entity.
- *
- * A method with the same name as the component ID is considered to be a constructor
+ * There is a convention for writing components. Properties or
+ * methods that start with an underscore are considered private.
+ * A method called `init` will automatically be called as soon as the
+ * component is added to an entity.
+ * A method with the same name as the component is considered to be a constructor
* and is generally used when data is needed before executing.
+ *
+ * ~~~
+ * Crafty.c("Annoying", {
+ * _message: "HiHi",
+ * init: function() {
+ * this.bind("EnterFrame", function() { alert(this.message); });
+ * },
+ * annoying: function(message) { this.message = message; }
+ * });
+ *
+ * Crafty.e("Annoying").annoying("I'm an orange...");
+ * ~~~
+ * @see Crafty.e
*/
- c: function(id, fn) {
+ c: function (id, fn) {
components[id] = fn;
},
-
+
/**@
* #Crafty.trigger
* @category Core, Events
@@ -807,17 +844,17 @@ Crafty.extend({
* every global event and every entity that has a callback.
* @see Crafty.bind
*/
- trigger: function(event, data) {
+ trigger: function (event, data) {
var hdl = handlers[event], h, i, l;
//loop over every object bound
- for(h in hdl) {
- if(!hdl.hasOwnProperty(h)) continue;
-
+ for (h in hdl) {
+ if (!hdl.hasOwnProperty(h)) continue;
+
//loop over every handler within object
- for(i = 0, l = hdl[h].length; i < l; i++) {
- if(hdl[h] && hdl[h][i]) {
+ for (i = 0, l = hdl[h].length; i < l; i++) {
+ if (hdl[h] && hdl[h][i]) {
//if an entity, call with that context
- if(entities[h]) {
+ if (entities[h]) {
hdl[h][i].call(Crafty(+h), data);
} else { //else call with Crafty context
hdl[h][i].call(Crafty, data);
@@ -826,7 +863,7 @@ Crafty.extend({
}
}
},
-
+
/**@
* #Crafty.bind
* @category Core, Events
@@ -838,14 +875,14 @@ Crafty.extend({
* with the event name.
* @see Crafty.trigger, Crafty.unbind
*/
- bind: function(event, callback) {
- if(!handlers[event]) handlers[event] = {};
+ bind: function (event, callback) {
+ if (!handlers[event]) handlers[event] = {};
var hdl = handlers[event];
-
- if(!hdl.global) hdl.global = [];
+
+ if (!hdl.global) hdl.global = [];
return hdl.global.push(callback) - 1;
},
-
+
/**@
* #Crafty.unbind
* @category Core, Events
@@ -857,64 +894,64 @@ Crafty.extend({
* @returns True or false depending on if a callback was unbound
* Unbind any event from any entity or global event.
*/
- unbind: function(event, callback) {
+ unbind: function (event, callback) {
var hdl = handlers[event], h, i, l;
-
+
//loop over every object bound
- for(h in hdl) {
- if(!hdl.hasOwnProperty(h)) continue;
-
+ for (h in hdl) {
+ if (!hdl.hasOwnProperty(h)) continue;
+
//if passed the ID
- if(typeof callback === "number") {
+ if (typeof callback === "number") {
delete hdl[h][callback];
return true;
}
-
+
//loop over every handler within object
- for(i = 0, l = hdl[h].length; i < l; i++) {
- if(hdl[h][i] === callback) {
+ for (i = 0, l = hdl[h].length; i < l; i++) {
+ if (hdl[h][i] === callback) {
delete hdl[h][i];
return true;
}
}
}
-
+
return false;
},
-
+
/**@
* #Crafty.frame
* @category Core
* @sign public Number Crafty.frame(void)
* Returns the current frame number
*/
- frame: function() {
+ frame: function () {
return frame;
},
-
- components: function() {
+
+ components: function () {
return components;
},
-
- isComp: function(comp) {
+
+ isComp: function (comp) {
return comp in components;
},
-
- debug: function() {
+
+ debug: function () {
return entities;
},
-
+
/**@
* #Crafty.settings
* @category Core
* Modify the inner workings of Crafty through the settings.
*/
- settings: (function() {
+ settings: (function () {
var states = {},
callbacks = {};
-
+
return {
- /**@
+ /**@
* #Crafty.settings.register
* @comp Crafty.settings
* @sign public void Crafty.settings.register(String settingName, Function callback)
@@ -923,10 +960,10 @@ Crafty.extend({
* Use this to register custom settings. Callback will be executed when `Crafty.settings.modify` is used.
* @see Crafty.settings.modify
*/
- register: function(setting, callback) {
+ register: function (setting, callback) {
callbacks[setting] = callback;
},
-
+
/**@
* #Crafty.settings.modify
* @comp Crafty.settings
@@ -936,12 +973,12 @@ Crafty.extend({
* Modify settings through this method.
* @see Crafty.settings.register, Crafty.settings.get
*/
- modify: function(setting, value) {
- if(!callbacks[setting]) return;
+ modify: function (setting, value) {
+ if (!callbacks[setting]) return;
callbacks[setting].call(states[setting], value);
states[setting] = value;
},
-
+
/**@
* #Crafty.settings.get
* @comp Crafty.settings
@@ -951,12 +988,12 @@ Crafty.extend({
* Returns the current value of the setting.
* @see Crafty.settings.register, Crafty.settings.get
*/
- get: function(setting) {
+ get: function (setting) {
return states[setting];
}
};
})(),
-
+
clone: clone
});
View
18 src/drawing.js
@@ -28,12 +28,6 @@ Crafty.c("Color", {
*
* The argument must be a color readable depending on which browser you
* choose to support. IE 8 and below doesn't support the rgb() syntax.
- *
- * @example
- * ~~~
- * Crafty.e("2D, DOM, Color")
- * .color("#969696");
- * ~~~
*/
color: function(color) {
this._color = color;
@@ -73,11 +67,6 @@ Crafty.c("Tint", {
* @param color - The color in hexidecimal
* @param strength - Level of opacity
* Modify the color and level opacity to give a tint on the entity.
- * @example
- * ~~~
- * Crafty.e("2D, Canvas, Tint")
- * .tint("#969696", 0.3);
- * ~~~
*/
tint: function(color, strength) {
this._strength = strength;
@@ -211,13 +200,6 @@ Crafty.extend({
*
* When a scene is played a SceneChange event is triggered. The callback object has
* the properties oldScene and newScene, which are string names of the scenes.
- *
- * @example
- * ~~~
- * Crafty.scene("loading", function() {});
- *
- * Crafty.scene("loading");
- * ~~~
*/
scene: function(name, fn) {
//play scene
View
4 src/sound.js
@@ -69,7 +69,6 @@ Crafty.extend({
* //only one format
* Crafty.audio.add("jump", "sounds/jump.mp3");
* ~~~
- * @see Crafty.audio.play, Crafty.audio.settings
*/
add: function(id, url) {
if(!Crafty.support.audio) return this;
@@ -152,6 +151,7 @@ Crafty.extend({
},
/**@
* #Crafty.audio.play
+ * @comp Crafty.audio
* @sign public this Crafty.audio.play(String id)
* @sign public this Crafty.audio.play(String id, Number repeatCount)
* @param id - A string to reffer to sounds
@@ -169,7 +169,6 @@ Crafty.extend({
* //play and repeat forever
* Crafty.audio.play("backgroundMusic", -1);
* ~~~
- * @see Crafty.audio.add, Crafty.audio.settings
*/
play: function(id, repeat) {
if(!Crafty.support.audio) return;
@@ -249,7 +248,6 @@ Crafty.extend({
* Crafty.audio.mute(true);
* Crafty.audio.mute(false);
* ~~~
-
*/
mute: function(mute) {
var sounds, sound, i, l, elem;
View
46 src/storage.js
@@ -5,18 +5,21 @@
*/
/**@
* #.open
+ * @comp Storage
* @sign .open(String gameName)
- * @param gameName - a machine-readable string to uniquely identify your game
+ * @param gameName - a machine readable string to uniquely identify your game
* Opens a connection to the database. If the best they have is localstorage or lower, it does nothing
*
* @example
* Open a database
- * ---------------
+ * ~~~
* Crafty.storage.open('MyGame');
+ * ~~~
*/
/**@
* #.save
+ * @comp Storage
* @sign .save(String key, String type, Mixed data)
* @param key - A unique key for identifying this piece of data
* @param type - 'save' or 'cache'
@@ -28,15 +31,17 @@
*
* @example
* Saves an entity to the database
- * ----------------
+ * ~~~
* var ent = Crafty.e("2D, DOM")
- * .attr({x: 20, y: 20, w: 100, h:100});
+ * .attr({x: 20, y: 20, w: 100, h:100});
* Crafty.storage.open('MyGame');
* Crafty.storage.save('MyEntity', 'save', ent);
+ * ~~~
*/
/**@
* #.load
+ * @comp Storage
* @sign .load(String key, String type)
* @param key - A unique key to search for
* @param type - 'save' or 'cache'
@@ -46,41 +51,48 @@
* @example
* Loads an entity from the database
- * ------------------
+ * ~~~
* Crafty.storage.open('MyGame');
* Crafty.storage.load('MyEntity', 'save', function (data) { // do things });
+ * ~~~
*/
/**@
* #.getAllKeys
+ * @comp Storage
* @sign .getAllKeys(String type)
* @param type - 'save' or 'cache'
* Gets all the keys for a given type
* @example
* Gets all the save games saved
- * ------------------
+ * ~~~
* Crafty.storage.open('MyGame');
* var saves = Crafty.storage.getAllKeys('save');
+ * ~~~
*/
/**@
* #.external
+ * @comp Storage
* @sign .external(String url)
* @param url - URL to an external to save games too
* Enables and sets the url for saving games to an external server
* @example
* Save an entity to an external server
- * --------------------------
+ * ~~~
* Crafty.storage.external('http://somewhere.com/server.php');
* Crafty.storage.open('MyGame');
* var ent = Crafty.e('2D, DOM')
- * .attr({x: 20, y: 20, w: 100, h:100});
+ * .attr({x: 20, y: 20, w: 100, h:100});
* Crafty.storage.save('save01', 'save', ent);
+ * ~~~
+ */
/**@
- * SaveData event
+ * #SaveData event
+ * @comp Storage
* @param data - An object containing all of the data to be serialized
* @param prepare - The function to prepare an entity for serialization
* Any data a component wants to save when it's serialized should be added to this object.
@@ -89,16 +101,17 @@
*
* @example
* Saves the innerHTML of an entity
- * ---------
+ * ~~~
* Crafty.e("2D DOM").bind("SaveData", function (data, prepare) {
- * data.attr.x = this.x;
- * data.attr.y = this.y;
- * data.dom = this.element.innerHTML;
+ * data.attr.x = this.x;
+ * data.attr.y = this.y;
+ * data.dom = this.element.innerHTML;
* });
+ * ~~~
*/
/**@
- * LoadData event
+ * #LoadData event
* @param data - An object containing all the data that been saved
* @param process - The function to turn a string into an entity
* Handlers for processing any data that needs more than straight assignment
@@ -107,11 +120,12 @@
* It does not need to be handled here
*
* @example
- * ---------
+ * ~~~
* Sets the innerHTML from a saved entity
* Crafty.e("2D DOM").bind("LoadData", function (data, process) {
- * this.element.innerHTML = data.dom;
+ * this.element.innerHTML = data.dom;
* });
+ * ~~~
*/
Crafty.storage = (function () {

0 comments on commit 040f7c4

Please sign in to comment.