Merge pull request #146 from cursedcoder/update-docs

Reorganize documentation and update old stuff

CONTRIBUTING.md

@@ -29,21 +29,18 @@ steps to reproduce, etc. "X isn't working!!!1!" will probably just be closed.
 ## Making Changes
 
 To build the library you will need to download node.js from [nodejs.org][20]. After it has been installed open a
-console and run `npm install -g gulp` to install the global `gulp` executable.
+console and run `npm install -g yarn` to install the global `yarn` executable.
 
 After that you can clone the repository and run `npm install` inside the cloned folder. This will install
-dependencies necessary for building the project. You can rebuild the project by running `gulp` in the cloned
+dependencies necessary for building the project. You can rebuild the project by running `yarn build` in the cloned
 folder.
 
 Once that is ready, you can make your changes and submit a Pull Request:
 
 - **Send Pull Requests to the `master` branch.** All Pull Requests must be sent to the `master` branch, which is where
 all "bleeding-edge" development takes place.
 
-- **Ensure changes are jshint validated.** Our JSHint configuration file is provided in the repository and you
-should check against it before submitting. This should happen automatically when running `gulp` in the repo directory.
-
-- **Never commit new builds.** When making a code change you should always run `gulp` which will rebuild the project
+- **Never commit new builds.** When making a code change you should always run `yarn build` which will rebuild the project
 so you can test, *however* please do not commit the new builds placed in `dist/` or your PR will be closed. By default
 the build process will output to an ignored folder (`build/`) you should be fine.
 
@@ -52,16 +49,3 @@ The more focused a PR is, the faster it will get attention and be merged. Extra
 trash files will likely get your PR closed.
 
 [20]: http://nodejs.org
-
-
-## Quickie Code Style Guide
-
-Use EditorConfig and JSHint! Both tools will ensure your code is in the required styles! Either way, here are some tips:
-
-- Use 4 spaces for tabs, never tab characters.
-
-- No trailing whitespace, blank lines should have no whitespace.
-
-- Always favor strict equals `===` unless you *need* to use type coercion.
-
-- Follow conventions already in the code, and listen to jshint. Our config is set-up for a reason.

README.md

@@ -2,198 +2,77 @@
 
 Spine implementation for pixi v3 and pixi v4.
 
-## Spine version
-
-Pixi-spine 1.3.x works ONLY with data exported from Spine 3.5. 
-
-Please enable "beta updates" and re-export everything from the spine editor.
-
-According to spine runtime license, you can use runtime only if you have bought the editor, so exporting latest versions of animations shouldn't be a problem for you.
-
 ## Usage
 
 ### Prebuilt Files
 
 If you are just including the built files, pixi spine adds itself to a pixi namespace:
 
 ```js
-PIXI.loader
-    .add('spineCharacter', 'spine-data-1/HERO.json')
-    .load(function (loader, resources) {
-        var animation = new PIXI.spine.Spine(resources.spineCharacter.spineData);
-
-        // add the animation to the scene and render...
-    });
-```
-
-### Typescript
-
-There's "bin/pixi-spine.d.ts" file, you can use it.
-
-### How to use spine events
-
-spine-ts way
-
-```js
-animation.state.addListener({
-    event: function(entry, event) { console.log('event fired '+event.data+' at track' + entry.trackIndex) },
-    complete: function(entry) { console.log('track '+trackIndex+' completed '+entry.loopsCount()+' times') },
-    start: function(entry) { console.log('animation is set at '+entry.trackIndex) },
-    end: function(entry) { console.log('animation was ended at '+entry.trackIndex) },
-
-
-    dispose: function(entry) { console.log('animation was disposed at '+entry.trackIndex) },
-    interrupted: function(entry) { console.log('animation was interrupted at '+entry.trackIndex) }
-})
-
-animation.state.addAnimation(0, 'walk', true);
-animation.state.tracks[0].listener = { 
-    complete: function(trackEntry, count) { console.log('my track completed '+entry.loopsCount()+' times') }
-}
-
+new PIXI.spine.Spine();
 ```
 
-DEPRECATED, OLD WAY:
+### Basic example
 
 ```js
-animation.state.onEvent = function(trackIndex, event) { console.log('event fired '+event.data) }
-animation.state.onComplete = function(trackIndex, loopCount) { console.log('track '+trackIndex+' completed '+count+' times') }
-animation.state.onStart =function(trackIndex) { console.log('animation is set at '+trackIndex) }
-animation.state.onEnd = function(trackIndex) { console.log('animation was ended at '+trackIndex) }
-//same for track, if it exists
-animation.state.addAnimation(0, 'walk', true);
-animation.state.tracks[0].onEnd = function(trackIndex, count) { console.log('my track ended :)') }
-```
-
-### How to choose resolution
-
-Use with [pixi-compressed-textures.js](https://github.com/pixijs/pixi-compressed-textures)
+var app = new PIXI.Application();
 
-```js
-//choose preferred resolution and texture type
-PIXI.loader.before(PIXI.compressedTextures.extensionChooser(["@2x.atlas"]));
-//specify what resolutions are available for spine animations
-var options = { metadata: { spineMetadata: { choice: ["@.5x.atlas", "@2x.atlas"] } } };
+document.body.appendChild(app.view);
 
 PIXI.loader
-    .add('spineCharacter', 'spine-data-1/HERO.json', options);
+    .add('spineCharacter', 'spine-data-1/HERO.json')
     .load(function (loader, resources) {
         var animation = new PIXI.spine.Spine(resources.spineCharacter.spineData);
-    });
-```
-
-### How to use pre-loaded json and atlas files
-
-```js
-var rawSkeletonData = JSON.parse("$jsondata"); //your skeleton.json file here
-var rawAtlasData = "$atlasdata"; //your atlas file 
-
-var spineAtlas = new PIXI.spine.core.TextureAtlas(rawAtlasData, function(line, callback) {
-    //pass the image here.
-    callback(PIXI.BaseTexture.fromImage(line));
-}); //specify path, image.png will be added automatically
-
-var spineAtlasLoader = new PIXI.spine.core.AtlasAttachmentLoader(spineAtlas)
-var spineJsonParser = new PIXI.spine.core.SkeletonJson(spineAtlasLoader);
-var spineData = spineJsonParser.readSkeletonData(rawSkeletonData);
 
-//now we can create spine instance
-var spine = new PIXI.spine(spineData);
-```
-
-### How to use pixi spritesheet with it
-
-See [examples/](examples/dynamic_texture_atlas.md).
-
-### How to change atlas file extension (I hate IIS webserver)
-
-```js
-var spineLoaderOptions = { metadata: { spineAtlasSuffix: '.txt' } };
-PIXI.loader
-    .add('pixie', '_assets/spine/Pixie.json', spineLoaderOptions)
-    .load(onAssetsLoaded);
-```
-
-### How to run animation
-
-```js
-var spineBoy = new PIXI.spine.Spine(spineBoyData);
-if (spineBoy.state.hasAnimation('run')) {
-    //run forever, little boy!
-    spineBoy.state.setAnimation(0, 'run', true);
-    //dont run too fast
-    spineBoy.state.timeScale = 0.1;
-}
+        // add the animation to the scene and render...
+        app.stage.addChild(animation);
+
+        // run 
+        var animation = new PIXI.spine.Spine(spineBoyData);
+        if (animation.state.hasAnimation('run')) {
+            // run forever, little boy!
+            animation.state.setAnimation(0, 'run', true);
+            // dont run too fast
+            animation.state.timeScale = 0.1;
+        }
+
+        app.start();
+    });
 ```
-
-### Changing Skins
-Once skins are defined in Spine, it's possible to change them in runtime. According to the Spine libraries:
->If skin is already set, new skin can change only slots attached in old skin.
 
-So if a skin has been set and another skin is to be set, it may result in the newer skin not showing. To workaround this issue, set the skin to null and then set the skin like so:
-
-```js
-var spineCharacter = new PIXI.spine.Spine(resources.boy.spineData);
-var skeleton = spineCharacter.skeleton;
-
-function setSkinByName(skinName) {
-  skeleton.setSkin(null);
-  skeleton.setSkinByName('darker');
-}
+## Using webpack or browserify?
 
-setSkinByName('lighter');
+Check out examples at our [sandbox](sandbox/README.md).
 
-```
-If the skin is changed whilst the spineCharacter is animating, there may be a problem with the draw order of some assets. This will resolve when the animation finishes it's loop or the animation is restarted.
-
-### Changing the texture the direct way (hacks)
-
-```js
-//let 'spine' be Spine object
-var spine = new PIXI.spine.Spine(loader.resources['spineBoy'].data);
-//let myTexture be the texture you are assigning. it can be something from the spritesheet
-var myTexture = loader.resources['newRegionTexture'].texture;
+## Typescript
 
-spine.hackTextureBySlotName('head', myTexture);
-
-//Region attachments are tricky: they must have width and height, specify it if your texture differs from old one
-spine.hackTextureBySlotName('arm', myTexture, { width: 100, height : 100 });
-//If you want texture have its natural size, pass it. pixiV3 - texture.frame, pixiV4 - texture.orig
-spine.hackTextureBySlotIndex(7, myTexture, texture.orig || texture.frame);
-```
+There's "bin/pixi-spine.d.ts" file, you can use it.
 
+## Spine version
 
-### How to use compressed textures
+Pixi-spine 1.3.x works ONLY with data exported from Spine 3.5. 
 
-```js
-PIXI.loader.before(PIXI.compressedTextures.extensionChooser(["@2x.atlas", ".dds"]));
-var options = { metadata: { spineMetadata: { choice: ["@.5x.atlas", "@2x.atlas"] }, imageMetadata: { choice: [".dds", ".pvr"] } } };
+Please enable "beta updates" and re-export everything from the spine editor.
 
-PIXI.loader
-    .add('spineCharacter', 'spine-data-1/HERO.json', options);
-    .load(function (loader, resources) {
-        var animation = new PIXI.spine.Spine(resources.spineCharacter.spineData);
-    });
-```
+According to spine runtime license, you can use runtime only if you have bought the editor, so exporting latest versions of animations shouldn't be a problem for you.
 
 ## Building
 
-You will need to have [node][node] or [typescript][typescript] setup on your machine.
+You will need to have [node][node] setup on your machine.
 
-Then you can install dependencies and build:
+Make sure you have [yarn][yarn] installed:
 
-```bash
-npm i && npm run build
-```
+    npm install -g yarn
 
-Or you can just use typescript compiler
+Then you can install dependencies and build:
 
 ```bash
-tsc
+yarn
+yarn build
 ```
 
 That will output the built distributables to `./bin`.
 
-[node]:       http://nodejs.org/
-[gulp]:       http://gulpjs.com/
+[node]:             https://nodejs.org/
 [typescript]:       https://www.typescriptlang.org/
+[yarn]:             https://yarnpkg.com

examples/change_atlas_extension.md

@@ -0,0 +1,8 @@
+### How to change atlas file extension (I hate IIS webserver)
+
+```js
+var spineLoaderOptions = { metadata: { spineAtlasSuffix: '.txt' } };
+PIXI.loader
+    .add('pixie', '_assets/spine/Pixie.json', spineLoaderOptions)
+    .load(onAssetsLoaded);
+```

examples/change_skin.md

@@ -0,0 +1,19 @@
+### Changing Skins
+Once skins are defined in Spine, it's possible to change them in runtime. According to the Spine libraries:
+>If skin is already set, new skin can change only slots attached in old skin.
+
+So if a skin has been set and another skin is to be set, it may result in the newer skin not showing. To workaround this issue, set the skin to null and then set the skin like so:
+
+```js
+var spineCharacter = new PIXI.spine.Spine(resources.boy.spineData);
+var skeleton = spineCharacter.skeleton;
+
+function setSkinByName(skinName) {
+  skeleton.setSkin(null);
+  skeleton.setSkinByName(skinName);
+}
+
+setSkinByName('lighter');
+
+```
+If the skin is changed whilst the spineCharacter is animating, there may be a problem with the draw order of some assets. This will resolve when the animation finishes it's loop or the animation is restarted.

examples/compressed_textures.md

@@ -0,0 +1,12 @@
+### How to use compressed textures
+
+```js
+PIXI.loader.before(PIXI.compressedTextures.extensionChooser(["@2x.atlas", ".dds"]));
+var options = { metadata: { spineMetadata: { choice: ["@.5x.atlas", "@2x.atlas"] }, imageMetadata: { choice: [".dds", ".pvr"] } } };
+
+PIXI.loader
+    .add('spineCharacter', 'spine-data-1/HERO.json', options)
+    .load(function (loader, resources) {
+        var animation = new PIXI.spine.Spine(resources.spineCharacter.spineData);
+    });
+```

examples/hack_texture.md

@@ -0,0 +1,15 @@
+### Changing the texture the direct way (hacks)
+
+```js
+//let 'spine' be Spine object
+var spine = new PIXI.spine.Spine(loader.resources['spineBoy'].data);
+//let myTexture be the texture you are assigning. it can be something from the spritesheet
+var myTexture = loader.resources['newRegionTexture'].texture;
+
+spine.hackTextureBySlotName('head', myTexture);
+
+//Region attachments are tricky: they must have width and height, specify it if your texture differs from old one
+spine.hackTextureBySlotName('arm', myTexture, { width: 100, height : 100 });
+//If you want texture have its natural size, pass it. pixiV3 - texture.frame, pixiV4 - texture.orig
+spine.hackTextureBySlotIndex(7, myTexture, texture.orig || texture.frame);
+```

examples/index.md

@@ -0,0 +1,11 @@
+pixi-spine docs
+===============
+
+1. [How to change atlas file extension (I hate IIS webserver)](change_atlas_extension.md)
+2. [Changing Spine Skins](change_skin.md)
+3. [How to use compressed textures](compressed_textures.md)
+4. [How to make dynamic texture atlas (without .atlas file)](dynamic_texture_atlas.md)
+5. [Changing the texture the direct way (hacks)](hack_texture.md)
+6. [How to use pre-loaded json and atlas files](preloaded_json.md)
+7. [How to use spine events](spine_events.md)
+8. [How to choose resolution](texture_and_sprite_resolution.md)

examples/preloaded_json.md

@@ -0,0 +1,18 @@
+### How to use pre-loaded json and atlas files
+
+```js
+var rawSkeletonData = JSON.parse("$jsondata"); //your skeleton.json file here
+var rawAtlasData = "$atlasdata"; //your atlas file 
+
+var spineAtlas = new PIXI.spine.core.TextureAtlas(rawAtlasData, function(line, callback) {
+    // pass the image here.
+    callback(PIXI.BaseTexture.fromImage(line));
+}); // specify path, image.png will be added automatically
+
+var spineAtlasLoader = new PIXI.spine.core.AtlasAttachmentLoader(spineAtlas)
+var spineJsonParser = new PIXI.spine.core.SkeletonJson(spineAtlasLoader);
+var spineData = spineJsonParser.readSkeletonData(rawSkeletonData);
+
+// now we can create spine instance
+var spine = new PIXI.spine.Spine(spineData);
+```