kontra
Version:
Kontra HTML5 game development library
491 lines (437 loc) • 18 kB
HTML
<html lang="en">
<head>
<title>Kontra.js – SpriteSheet</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<base href="https://straker.github.io/kontra/">
<script>
// adjust path based on location (github pages required kontra url)
if (window.location.host.indexOf('localhost') !== -1) {
let base = document.querySelector('base');
base.setAttribute('href', '/');
}
</script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.16.0/themes/prism.min.css">
<link rel="stylesheet" href="assets/styles.css">
<script src="assets/js/kontra.js"></script>
</head>
<body>
<div class="content">
<header class="main-nav">
<div id="kontra-heading" class="nav-heading">Kontra</div>
<a href="#main">Skip navigation</a>
<nav>
<button class="menu-button" aria-expanded="false" aria-controls="menu"><span aria-hidden="true">☰</span> Menu</button>
<!-- add role=list back to list so screen readers still read it as list when
css list-style: none is set
@see https://web-a11y.slack.com/archives/C042TSFGN/p1501699529181172 -->
<ul id="menu" role="list">
<li><a href="." >Introduction</a></li>
<li><a href="getting-started" >Getting Started</a></li>
<li><a href="download" >Download</a></li>
<li><a href="tutorials" >Tutorials</a></li>
<li><a href="made-with-kontra" >Made With Kontra</a></li>
<li>
<span id="api" class="nav-api-heading">API</span>
<ul aria-labelledby="api">
<li><a href="api/animation" >Animation</a></li>
<li><a href="api/assets" >Assets</a></li>
<li><a href="api/core" >Core</a></li>
<li><a href="api/events" >Events</a></li>
<li><a href="api/gameLoop" >GameLoop</a></li>
<li><a href="api/keyboard" >Keyboard</a></li>
<li><a href="api/plugin" >Plugin</a></li>
<li><a href="api/pointer" >Pointer</a></li>
<li><a href="api/pool" >Pool</a></li>
<li><a href="api/quadtree" >Quadtree</a></li>
<li><a href="api/sprite" >Sprite</a></li>
<li><a href="api/spriteSheet" aria-current="page">SpriteSheet</a></li>
<li><a href="api/store" >Store</a></li>
<li><a href="api/tileEngine" >TileEngine</a></li>
<li><a href="api/vector" >Vector</a></li>
</ul>
</li>
</ul>
</nav>
<div class="scroll-indicator" aria-hidden="true"><span>^</span></div>
</header>
<main id="main">
<div>
<a href="https://github.com/straker/kontra" class="github-corner" aria-label="View source on GitHub"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#151513; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a>
<h1>SpriteSheet(​properties)
</h1>
<p>A sprite sheet to animate a sequence of images. Used to create <a href="./Sprite#animation-sprite">animation sprites</a>.</p>
<figure>
<a href="assets/imgs/character_walk_sheet.png">
<img src="assets/imgs/character_walk_sheet.png" alt="11 frames of a walking pill-like alien wearing a space helmet.">
</a>
<figcaption>Sprite sheet image courtesy of <a href="https://kenney.nl/assets">Kenney</a>.</figcaption>
</figure>
<p>Typically you create a sprite sheet just to create animations and then use the animations for your sprite.</p>
<div class="tablist">
<ul role="tablist">
<li role="presentation" data-tab="global">
<button role="tab" id="spritesheet-global-tab">Global Object</button>
</li>
<li role="presentation" data-tab="es">
<button role="tab" id="spritesheet-es-tab">ES Module Import</button>
</li>
<li role="presentation" data-tab="bundle">
<button role="tab" id="spritesheet-bundle-tab">Module Bundler</button>
</li>
<li role="presentation"></li>
</ul>
<section role="tabpanel" aria-labelledby=spritesheet-global-tab data-tabpanel="global"><pre><code class="language-js">let { Sprite, SpriteSheet } = kontra;
let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {
let spriteSheet = SpriteSheet({
image: image,
frameWidth: 72,
frameHeight: 97,
animations: {
// create a named animation: walk
walk: {
frames: '0..9', // frames 0 through 9
frameRate: 30
}
}
});
let sprite = Sprite({
x: 200,
y: 100,
// use the sprite sheet animations for the sprite
animations: spriteSheet.animations
});
};</code></pre></section>
<section role="tabpanel" aria-labelledby=spritesheet-es-tab data-tabpanel="es"><pre><code class="language-js">import { Sprite, SpriteSheet } from 'path/to/kontra.mjs';
let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {
let spriteSheet = SpriteSheet({
image: image,
frameWidth: 72,
frameHeight: 97,
animations: {
// create a named animation: walk
walk: {
frames: '0..9', // frames 0 through 9
frameRate: 30
}
}
});
let sprite = Sprite({
x: 200,
y: 100,
// use the sprite sheet animations for the sprite
animations: spriteSheet.animations
});
};</code></pre></section>
<section role="tabpanel" aria-labelledby=spritesheet-bundle-tab data-tabpanel="bundle"><pre><code class="language-js">import { Sprite, SpriteSheet } from 'kontra';
let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {
let spriteSheet = SpriteSheet({
image: image,
frameWidth: 72,
frameHeight: 97,
animations: {
// create a named animation: walk
walk: {
frames: '0..9', // frames 0 through 9
frameRate: 30
}
}
});
let sprite = Sprite({
x: 200,
y: 100,
// use the sprite sheet animations for the sprite
animations: spriteSheet.animations
});
};</code></pre></section>
</div>
<h3 id="title-SpriteSheet"><span class="visually-hidden">SpriteSheet</span> Parameters</span></h3>
<dl aria-labelledby="title-SpriteSheet">
<dt>
<code>properties</code>
</dt>
<dd><p>Object. Properties of the sprite sheet.</p>
</dd>
<dt>
<code>properties.image</code>
</dt>
<dd><p>Image or HTMLCanvasElement. The sprite sheet image.</p>
</dd>
<dt>
<code>properties.frameWidth</code>
</dt>
<dd><p>Number. The width of a single frame.</p>
</dd>
<dt>
<code>properties.frameHeight</code>
</dt>
<dd><p>Number. The height of a single frame.</p>
</dd>
<dt>
<code>properties.frameMargin</code>
<span class="optional">Optional</span>
</dt>
<dd><p>Number. The amount of whitespace between each frame. Defaults to <code>0</code>.</p>
</dd>
<dt>
<code>properties.animations</code>
<span class="optional">Optional</span>
</dt>
<dd><p>Object. Animations to create from the sprite sheet using <a href="Animation">Animation</a>. Passed directly into the sprite sheets <a href="#createAnimations">createAnimations()</a> function.</p>
</dd>
</dl>
<section class="toc">
<h2 id="toc"><a href="#toc" class="section-link">Table of Contents<span aria-hidden="true">#</span></a></h2>
<ul aria-labelledby="toc">
<li>
<h3 id="properties">Properties</h3>
<ul aria-labelledby="properties">
<li>
<a href="api/spriteSheet#animations">
<span>SpriteSheet​.animations</span>
</a>
</li>
<li>
<a href="api/spriteSheet#frame">
<span>SpriteSheet​.frame</span>
</a>
</li>
<li>
<a href="api/spriteSheet#image">
<span>SpriteSheet​.image</span>
</a>
</li>
</ul>
</li>
<li>
<h3 id="methods">Methods</h3>
<ul aria-labelledby="methods">
<li>
<a href="api/spriteSheet#createAnimations">
<span>SpriteSheet​.createAnimations(​animations)</span>
</a>
</li>
</ul>
</li>
</ul>
</section>
<section>
<h2 id="animations">
<a href="api/spriteSheet#animations" class="section-link">
<span>SpriteSheet​.animations</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>An object of named <a href="Animation">Animation</a> objects. Typically you pass this object into <a href="Sprite">Sprite</a> to create an <a href="./Sprite#animation-sprite">animation sprites</a>.</p>
</section>
<section>
<h2 id="createAnimations">
<a href="api/spriteSheet#createAnimations" class="section-link">
<span>SpriteSheet​.createAnimations(​animations)</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>Create named animations from the sprite sheet. Called from the constructor if the <code>animations</code> argument is passed.</p>
<p>This function populates the sprite sheets <code>animations</code> property with <a href="Animation">Animation</a> objects. Each animation is accessible by its name.</p>
<div class="tablist">
<ul role="tablist">
<li role="presentation" data-tab="global">
<button role="tab" id="createanimations-global-tab">Global Object</button>
</li>
<li role="presentation" data-tab="es">
<button role="tab" id="createanimations-es-tab">ES Module Import</button>
</li>
<li role="presentation" data-tab="bundle">
<button role="tab" id="createanimations-bundle-tab">Module Bundler</button>
</li>
<li role="presentation"></li>
</ul>
<section role="tabpanel" aria-labelledby=createanimations-global-tab data-tabpanel="global"><pre><code class="language-js">let { Sprite, SpriteSheet } = kontra;
let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {
let spriteSheet = SpriteSheet({
image: image,
frameWidth: 72,
frameHeight: 97,
// this will also call createAnimations()
animations: {
// create 1 animation: idle
idle: {
// a single frame
frames: 1
}
}
});
spriteSheet.createAnimations({
// create 4 animations: jump, walk, moonWalk, attack
jump: {
// sequence of frames (can be non-consecutive)
frames: [1, 10, 1],
frameRate: 10,
loop: false,
},
walk: {
// ascending consecutive frame animation (frames 2-6, inclusive)
frames: '2..6',
frameRate: 20
},
moonWalk: {
// descending consecutive frame animation (frames 6-2, inclusive)
frames: '6..2',
frameRate: 20
},
attack: {
// you can also mix and match, in this case frames [8,9,10,13,10,9,8]
frames: ['8..10', 13, '10..8'],
frameRate: 10,
loop: false,
}
});
};</code></pre></section>
<section role="tabpanel" aria-labelledby=createanimations-es-tab data-tabpanel="es"><pre><code class="language-js">import { Sprite, SpriteSheet } from 'path/to/kontra.mjs';
let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {
let spriteSheet = SpriteSheet({
image: image,
frameWidth: 72,
frameHeight: 97,
// this will also call createAnimations()
animations: {
// create 1 animation: idle
idle: {
// a single frame
frames: 1
}
}
});
spriteSheet.createAnimations({
// create 4 animations: jump, walk, moonWalk, attack
jump: {
// sequence of frames (can be non-consecutive)
frames: [1, 10, 1],
frameRate: 10,
loop: false,
},
walk: {
// ascending consecutive frame animation (frames 2-6, inclusive)
frames: '2..6',
frameRate: 20
},
moonWalk: {
// descending consecutive frame animation (frames 6-2, inclusive)
frames: '6..2',
frameRate: 20
},
attack: {
// you can also mix and match, in this case frames [8,9,10,13,10,9,8]
frames: ['8..10', 13, '10..8'],
frameRate: 10,
loop: false,
}
});
};</code></pre></section>
<section role="tabpanel" aria-labelledby=createanimations-bundle-tab data-tabpanel="bundle"><pre><code class="language-js">import { Sprite, SpriteSheet } from 'kontra';
let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {
let spriteSheet = SpriteSheet({
image: image,
frameWidth: 72,
frameHeight: 97,
// this will also call createAnimations()
animations: {
// create 1 animation: idle
idle: {
// a single frame
frames: 1
}
}
});
spriteSheet.createAnimations({
// create 4 animations: jump, walk, moonWalk, attack
jump: {
// sequence of frames (can be non-consecutive)
frames: [1, 10, 1],
frameRate: 10,
loop: false,
},
walk: {
// ascending consecutive frame animation (frames 2-6, inclusive)
frames: '2..6',
frameRate: 20
},
moonWalk: {
// descending consecutive frame animation (frames 6-2, inclusive)
frames: '6..2',
frameRate: 20
},
attack: {
// you can also mix and match, in this case frames [8,9,10,13,10,9,8]
frames: ['8..10', 13, '10..8'],
frameRate: 10,
loop: false,
}
});
};</code></pre></section>
</div>
<h3 id="title-createAnimations"><span class="visually-hidden">createAnimations</span> Parameters</span></h3>
<dl aria-labelledby="title-createAnimations">
<dt>
<code>animations</code>
</dt>
<dd><p>Object. Object of named animations to create from the sprite sheet.</p>
</dd>
<dt>
<code>animations.<name>.frames</code>
</dt>
<dd><p>Number or String or an Array of Numbers or String[]. The sequence of frames to use from the sprite sheet. It can either be a single frame (<code>1</code>), a sequence of frames (<code>[1,2,3,4]</code>), or a consecutive frame notation (<code>'1..4'</code>). Sprite sheet frames are <code>0</code> indexed.</p>
</dd>
<dt>
<code>animations.<name>.frameRate</code>
</dt>
<dd><p>Number. The number frames to display per second.</p>
</dd>
<dt>
<code>animations.<name>.loop</code>
<span class="optional">Optional</span>
</dt>
<dd><p>Boolean. If the animation should loop back to the beginning once completed. Defaults to <code>true</code>.</p>
</dd>
</dl>
</section>
<section>
<h2 id="frame">
<a href="api/spriteSheet#frame" class="section-link">
<span>SpriteSheet​.frame</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>An object that defines properties of a single frame in the sprite sheet. It has properties of <code>width</code>, <code>height</code>, and <code>margin</code>.</p>
<p><code>width</code> and <code>height</code> are the width of a single frame, while <code>margin</code> defines the amount of whitespace between each frame.</p>
</section>
<section>
<h2 id="image">
<a href="api/spriteSheet#image" class="section-link">
<span>SpriteSheet​.image</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>The sprite sheet image.</p>
</section>
</div>
</main>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.16.0/prism.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.16.0/components/prism-javascript.min.js"></script>
<script src="assets/js/navbar.js"></script>
<script src="assets/js/exampleTabList.js"></script>
</body>
</html>