kontra
Version:
Kontra HTML5 game development library
417 lines (370 loc) • 17 kB
HTML
<html lang="en">
<head>
<title>Kontra.js – Pool</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" aria-current="page">Pool</a></li>
<li><a href="api/quadtree" >Quadtree</a></li>
<li><a href="api/sprite" >Sprite</a></li>
<li><a href="api/spriteSheet" >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>Pool(​properties)
</h1>
<p>A fast and memory efficient <a href="https://gameprogrammingpatterns.com/object-pool.html">object pool</a> for sprite reuse. Perfect for particle systems or SHUMPs. The pool starts out with just one object, but will grow in size to accommodate as many objects as are needed.</p>
<p><canvas width="600" height="200" id="pool-example"></canvas></p>
<script src="assets/js/pool.js"></script>
<h3 id="title-Pool"><span class="visually-hidden">Pool</span> Parameters</span></h3>
<dl aria-labelledby="title-Pool">
<dt>
<code>properties</code>
</dt>
<dd><p>Object. Properties of the pool.</p>
</dd>
<dt>
<code>properties.create</code>
</dt>
<dd><p>Function. Function that returns a new object to be added to the pool when there are no more alive objects.</p>
</dd>
<dt>
<code>properties.maxSize</code>
<span class="optional">Optional</span>
</dt>
<dd><p>Number. The maximum number of objects allowed in the pool. The pool will never grow beyond this size. Defaults to <code>1024</code>.</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>
<ul>
<li><a href="api/pool#basic-use">Basic Use</a></li>
</ul>
</li>
<li>
<h3 id="properties">Properties</h3>
<ul aria-labelledby="properties">
<li>
<a href="api/pool#maxSize">
<span>Pool​.maxSize</span>
</a>
</li>
<li>
<a href="api/pool#objects">
<span>Pool​.objects</span>
</a>
</li>
<li>
<a href="api/pool#size">
<span>Pool​.size</span>
</a>
</li>
</ul>
</li>
<li>
<h3 id="methods">Methods</h3>
<ul aria-labelledby="methods">
<li>
<a href="api/pool#clear">
<span>Pool​.clear(​)</span>
</a>
</li>
<li>
<a href="api/pool#get">
<span>Pool​.get(​properties)</span>
</a>
</li>
<li>
<a href="api/pool#getAliveObjects">
<span>Pool​.getAliveObjects(​)</span>
</a>
</li>
<li>
<a href="api/pool#render">
<span>Pool​.render(​)</span>
</a>
</li>
<li>
<a href="api/pool#update">
<span>Pool​.update(​[dt])</span>
</a>
</li>
</ul>
</li>
</ul>
</section>
<section>
<h2 id="basic-use">
<a href="#basic-use" class="section-link">
<span>Basic Use</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>To use the pool, you must pass the <code>create()</code> function argument, which should return a new <a href="Sprite">Sprite</a> or object. This object will be added to the pool every time there are no more alive objects.</p>
<p>The object must implement the functions <code>update()</code>, <code>init()</code>, and <code>isAlive()</code>. If one of these functions is missing the pool will throw an error. <a href="Sprite">Sprite</a> defines these functions for you.</p>
<p>An object is available for reuse when its <code>isAlive()</code> function returns <code>false</code>. For a sprite, this is typically when its ttl is <code>0</code>.</p>
<p>When you want an object from the pool, use the pools <a href="#get">get()</a> function and pass it any properties you want the newly initialized object to have.</p>
<div class="tablist">
<ul role="tablist">
<li role="presentation" data-tab="global">
<button role="tab" id="basic-use-global-tab">Global Object</button>
</li>
<li role="presentation" data-tab="es">
<button role="tab" id="basic-use-es-tab">ES Module Import</button>
</li>
<li role="presentation" data-tab="bundle">
<button role="tab" id="basic-use-bundle-tab">Module Bundler</button>
</li>
<li role="presentation"></li>
</ul>
<section role="tabpanel" aria-labelledby=basic-use-global-tab data-tabpanel="global"><pre><code class="language-js">let { Pool, Sprite } = kontra;
let pool = Pool({
// create a new sprite every time the pool needs a new object
create: Sprite
});
// properties will be passed to the sprites init() function
pool.get({
x: 100,
y: 200,
width: 20,
height: 40,
color: 'red',
ttl: 60
});</code></pre></section>
<section role="tabpanel" aria-labelledby=basic-use-es-tab data-tabpanel="es"><pre><code class="language-js">import { Pool, Sprite } from 'path/to/kontra.mjs';
let pool = Pool({
// create a new sprite every time the pool needs a new object
create: Sprite
});
// properties will be passed to the sprites init() function
pool.get({
x: 100,
y: 200,
width: 20,
height: 40,
color: 'red',
ttl: 60
});</code></pre></section>
<section role="tabpanel" aria-labelledby=basic-use-bundle-tab data-tabpanel="bundle"><pre><code class="language-js">import { Pool, Sprite } from 'kontra';
let pool = Pool({
// create a new sprite every time the pool needs a new object
create: Sprite
});
// properties will be passed to the sprites init() function
pool.get({
x: 100,
y: 200,
width: 20,
height: 40,
color: 'red',
ttl: 60
});</code></pre></section>
</div>
<p>When you want to update or render all alive objects in the pool, use the pools <a href="#update">update()</a> and <a href="#render">render()</a> functions.</p>
<div class="tablist">
<ul role="tablist">
<li role="presentation" data-tab="global">
<button role="tab" id="basic-use-global-tab">Global Object</button>
</li>
<li role="presentation" data-tab="es">
<button role="tab" id="basic-use-es-tab">ES Module Import</button>
</li>
<li role="presentation" data-tab="bundle">
<button role="tab" id="basic-use-bundle-tab">Module Bundler</button>
</li>
<li role="presentation"></li>
</ul>
<section role="tabpanel" aria-labelledby=basic-use-global-tab data-tabpanel="global"><pre><code class="language-js">let { GameLoop } = kontra;
let loop = GameLoop({
update: function() {
pool.update();
},
render: function() {
pool.render();
}
});</code></pre></section>
<section role="tabpanel" aria-labelledby=basic-use-es-tab data-tabpanel="es"><pre><code class="language-js">import { GameLoop } from 'path/to/kontra.mjs';
let loop = GameLoop({
update: function() {
pool.update();
},
render: function() {
pool.render();
}
});</code></pre></section>
<section role="tabpanel" aria-labelledby=basic-use-bundle-tab data-tabpanel="bundle"><pre><code class="language-js">import { GameLoop } from 'kontra';
let loop = GameLoop({
update: function() {
pool.update();
},
render: function() {
pool.render();
}
});</code></pre></section>
</div>
</section>
<section>
<h2 id="clear">
<a href="api/pool#clear" class="section-link">
<span>Pool​.clear(​)</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>Clear the object pool. Removes all objects from the pool and resets its <a href="#size">size</a> to 1.</p>
</section>
<section>
<h2 id="get">
<a href="api/pool#get" class="section-link">
<span>Pool​.get(​properties)</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>Get and return an object from the pool. The properties parameter will be passed directly to the objects <code>init()</code> function. If you're using a <a href="Sprite">Sprite</a>, you should also pass the <code>ttl</code> property to designate how many frames you want the object to be alive for.</p>
<p>If you want to control when the sprite is ready for reuse, pass <code>Infinity</code> for <code>ttl</code>. You'll need to set the sprites <code>ttl</code> to <code>0</code> when you're ready for the sprite to be reused.</p>
<pre><code class="language-js">let sprite = pool.get({
// the object will get these properties and values
x: 100,
y: 200,
width: 20,
height: 40,
color: 'red',
// pass Infinity for ttl to prevent the object from being reused
// until you set it back to 0
ttl: Infinity
});</code></pre>
<h3 id="title-get"><span class="visually-hidden">get</span> Parameters</span></h3>
<dl aria-labelledby="title-get">
<dt>
<code>properties</code>
</dt>
<dd><p>Object. Properties to pass to the objects <code>init()</code> function.</p>
</dd>
</dl>
<h3><span class="visually-hidden">get</span> Return value</h3>
<p><p>The newly initialized object.</p>
</p>
</section>
<section>
<h2 id="getAliveObjects">
<a href="api/pool#getAliveObjects" class="section-link">
<span>Pool​.getAliveObjects(​)</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>Returns an array of all alive objects. Useful if you need to do special processing on all alive objects outside of the pool, such as add all alive objects to a <a href="Quadtree">Quadtree</a>.</p>
<h3><span class="visually-hidden">getAliveObjects</span> Return value</h3>
<p><p>An Array of all alive objects.</p>
</p>
</section>
<section>
<h2 id="maxSize">
<a href="api/pool#maxSize" class="section-link">
<span>Pool​.maxSize</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>The maximum number of objects allowed in the pool. The pool will never grow beyond this size.</p>
</section>
<section>
<h2 id="objects">
<a href="api/pool#objects" class="section-link">
<span>Pool​.objects</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>All objects currently in the pool, both alive and not alive.</p>
</section>
<section>
<h2 id="render">
<a href="api/pool#render" class="section-link">
<span>Pool​.render(​)</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>Render all alive objects in the pool by calling the objects <code>render()</code> function.</p>
</section>
<section>
<h2 id="size">
<a href="api/pool#size" class="section-link">
<span>Pool​.size</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>The number of alive objects.</p>
</section>
<section>
<h2 id="update">
<a href="api/pool#update" class="section-link">
<span>Pool​.update(​[dt])</span>
<span aria-hidden="true">#</span>
</a>
</h2>
<p>Update all alive objects in the pool by calling the objects <code>update()</code> function. This function also manages when each object should be recycled, so it is recommended that you do not call the objects <code>update()</code> function outside of this function.</p>
<h3 id="title-update"><span class="visually-hidden">update</span> Parameters</span></h3>
<dl aria-labelledby="title-update">
<dt>
<code>dt</code>
<span class="optional">Optional</span>
</dt>
<dd><p>Number. Time since last update.</p>
</dd>
</dl>
</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>