Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kittykatattack/hexi

Make games the fun way!
https://github.com/kittykatattack/hexi

Last synced: 3 months ago
JSON representation

Make games the fun way!

Awesome Lists containing this project

README 

        
![Hexi](/tutorials/screenshots/logoAndIllustration.png)



Hexi

====



**Hexi** is a fun and easy way to make HTML5 games or any other

kind interactive media using pure JavaScript code. Take a look at 

the feature list and the [examples](https://github.com/kittykatattack/hexi/tree/master/examples) folder to get started. Keep scrolling, 

and you'll find a complete Quick Start Guide and beginner's tutorials ahead. If you've never made a game before, the tutorials are the best place to start.



What's great about Hexi? You get all the power of WebGL rendering with

a streamlined API that lets you write your code in a

[minimalist](https://en.wikipedia.org/wiki/Haiku),

[declarative](http://latentflip.com/imperative-vs-declarative/) way.

It makes coding a game as easy and fun as writing poetry or drawing. Try it! If you

need any help or have any questions, post something in this

repository's [Issues](https://github.com/kittykatattack/hexi/issues).

The Issues page is is Hexi's friendly chat room - don't be afraid to

ask for help :) 



You only need one file from this repository to get started using Hexi:

[`hexi.min.js`](https://github.com/kittykatattack/hexi/blob/master/bin/hexi.min.js). That's all! [Link it to your HTML document with a `` tag](http://www.quackit.com/javascript/tutorial/external_javascript_file.cfm), and go for it! 

Hexi has been written, from the ground up, in the latest version of

JavaScript (ES6/7, 20015/6) but is compiled down to ES5 (using [Babel](https://babeljs.io)) so that it will run anywhere. What do you need to know before you start using Hexi? You should have a reasonable understanding of HTML and JavaScript. You don't have to be an expert, just an ambitious beginner with an eagerness to learn. If you don't know HTML and JavaScript, the best place to start learning it is this book:



[Foundation Game Design with HTML5 and JavaScript](http://www.apress.com/9781430247166)



I know for a fact that it's the best book, because I wrote it!



Ok, got it? Do you know what JavaScript variables, functions, arrays and objects are and how to use them? Do you know what [JSON data files](http://www.copterlabs.com/blog/json-what-it-is-how-it-works-how-to-use-it/) are? Have you used the [Canvas Drawing API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Drawing_graphics_with_canvas)? Then you're ready to start using Hexi!  



Of course, Hexi is completely free to use: for-anything, for-ever! It was written in Canada (Toronto, Hamilton), India (Kullu Valley, Ladakh), Nepal (Kathmandu, Pokhara, Annapurna Base Camp), Thailand (Ko Phangan, Ko Tao) and South Africa (Cape Town), and is the result of 15 years' research into API usability for game design. The name, "Hexi" comes from ["Hex"](https://en.wiktionary.org/wiki/hex) + ["Pixi"](https://github.com/pixijs/pixi.js/) = "Hexi". [It has absolutely no other meaning](https://www.youtube.com/watch?v=XYGmNs6274A).



### Table of contents:

1. [Hexi's Features](#features)

2. [Modules](#modules)

3. [Quick start](#quickstart)

  1. [The HTML container page](#thehtmlcontainer)

  3. [Hexi's architecture](#hexisarchitecture)

  2. [Setting up and starting Hexi](#settingupandstartinghexi)

  4. [The load function](#theloadfunction)

  5. [The setup function](#thesetupfunction)

  6. [The play function](#thesplayfunction)

  7. [Taking it further](#takingitfurther)

4. [Tutorials](#tutorials)

  1. [Treasure Hunter](#treasure)

    1. [Setting up the HTML container page](#settingup)

    2. [Initializing the Ga engine](#initializing)

    3. [Define your "global" variables](#defineglobals)

    4. [Initialize your game with a setup function](#setupfunction)

      1. [Customizing the canvas](#customizing)

      2. [Creating the `chimes` sound object](#creatingsound)

      3. [Creating game scenes](#gamescenes)

      4. [Making sprites](#makingsprites)

      5. [Positioning sprites](#positioningsprites)

      6. [Assigning dynamic properties](#dynamicproperties)

      7. [Creating the enemy sprites](#enemysprites)

      8. [The health bar](#healthbar)

      9. [The game over scene](#gameoverscene)

      10. [Keyboard interactivity](#keyboard)

      11. [Setting the game state](#gamestate)

    5. [Game logic with the play function loop](#gamelogic)

      1. [Moving the player sprite](#movingplayer)

      2. [Containing sprites inside the screen boundaries](#boundries)

      3. [Collision with the enemies](#collisionenemy)

        1. [Collision with the treasure](#collisiontreasure)

      4. [Ending the game](#endinggame1)

    6. [Using images](#usingimages)

      1. [Individual images](#individualimages)

        1. [Loading image files](#loadingimagefile)

        2. [Making sprites with images](#makingsprites)

        3. [Fine-tuning the containment area](#finetuning)

    7. [Using a texture atlas](#textureatlas)

      1. [Preparing the images](#preparingimages)

      2. [loading the texture atlas](#loadingatlas)

  2. [Alien Armada](#alienarmada)

    1. [Load and use a custom font](#customfonts)

    2. [Scale and center the game in the browser](#scalebrowser)

    3. [A loading progress bar](#progressbar)

    4. [Shooting bullets](#shootingbullets)

    5. [Sprite states](#spritestates)

    6. [Generating random aliens](#randomaliens)

      1. [Timing the aliens](#timingaliens)

      2. [The aliens' random start positions](#randomposition)

    7. [Moving the aliens](#movingaliens)

    8. [Making the aliens explode](#explodealiens)

    9. [Displaying the score](#displayingscore)

    10. [Ending and resetting the game](#endinggame2)

  3. [Flappy Fairy!](#flappyfairy)

    1. [Make a button](#makeabutton)

    2. [Making the fairy fly](#makingthefairyfly)

    3. [Make a scrolling background](#makeascrollingbackground)

    4. [The fairy dust explosions](#thefairydustexplosions)

    5. [Use a particle emitter](#useaparticleemitter)

    6. [Creating and moving the pillars](#creatingandmovingthepillars)

5. [Integration with HTML and CSS](#htmlIntegration)

6. [A Guide to the examples](#aguidetotheexamples)



<a id='features'></a>

Features

--------



Here's Hexi's core feature list:



- All the most important sprites you need: rectangles, circles, lines,

  text, image sprites and animated "MovieClip" style sprites. You can make any of these sprites with one only line of code. You can also create your own custom sprite types.

- A complete scene graph with nested child-parent hierarchies (including

  a `stage`, and `addChild`/`removeChild` methods), local and global

  coordinates, depth layers, and rotation pivots.

- `group` sprites together to make game scenes. 

- A game loop with a user-definable `fps` and fully customizable and

  drop-dead-simple game state manager. `pause` and `resume` the game

  loop at any time.

- Tileset (spritesheet) support using `frame` and `filmstrip` methods to make

  sprites using tileset frames.

- Built-in texture atlas support for the popular Texture Packer

  format. 

- A keyframe animation and state manager for sprites. Use `show` to

  display a sprite's image state. Use `playAnimation` to play

  a sequence of frames (in a `loop` if you want to). Use

  `show` to display a specific frame number. Use `fps` to set the

  frame rate for sprite animations which is independent from the game's

  frame rate.

- Interactive `button` sprites with `up`, `over` and `down` states.

- Any sprite can be set to `interact` to receive mouse and touch

  actions.

  Intuitive `press`, `release`, `over`, `out` and `tap` methods for buttons and interactive

  sprites.

- Easy-to-use keyboard key bindings. Easily define your own with the `keyboard`

  method.

- A built-in universal `pointer` that works with both the mouse and

  touch. Assign your own custom `press`, `release` and `tap` methods

  or use any of the pointer's built-in properties: `isUp`, `isDown`,

  `tapped`, `x` and `y`. Define as many pointers as you need for multi-touch. (It also works with isometric maps!)

- Conveniently position sprites relative to other sprites using

  `putTop`, `putRight`, `putBottom`, `putLeft` and `putCenter`. Align

  sprites horizontally or vertically using `flowRight`, `flowLeft`,

  `flowUp` or `flowDown`.

- A universal asset loader to pre-load images, fonts, sounds and JSON

  data files. All popular file formats are supported. You can load new assets into the game at any time.

- An optional `load` state that lets you run actions while assets are

  loading. You can use the `load` state to add a loading progress bar.

- A fast and focused [Pixi-based](https://github.com/pixijs/pixi.js/) rendering engine. If Pixi can do it, so can Hexi! Hexi 

  is just a thin layer of code that sits on top of Pixi. And you can access the

  global `PIXI` object at any time to write pure Pixi code directly if you want

  to. Hexi includes the latest stable version of Pixi v3.0 automatically bundled for you.

- A sophisticated game loop using a fixed timestep with variable rendering

  and sprite interpolation. That means you get butter-smooth sprite animations

  at any framerate.

- A compact and powerful "Haiku" style API that's centered on shallow,

  composable components. Get more done writing less code.

- Import and play sounds using a built-in WebAudio API sound manager.

  Control sounds with `play`, `pause`, `stop`, `restart`,

  `playFrom`, `fadeIn` and `fadeOut` methods. Change a sound's `volume` and `pan`.

- Generate your own custom sound effects from pure code with

  the versatile `soundEffect` method.

- Shake sprites or the screen with `shake`.

- Tween functions for sprite and scene transitions: `slide`,

  `fadeIn`, `fadeOut`, `pulse`, `breathe`, `wobble`, `strobe` and

  some useful low-level tweening methods to help you create your own

  custom tweens.

- Make a sprite follow a connected series of waypoints with `walkPath`

  and `walkCurve`. 

- A handful of useful convenience functions: `followEase`,

  `followConstant`,

  `angle`, `distance`, `rotateAroundSprite`, `rotateAroundPoint`, `wait`,

  `randomInt`, `randomFloat`, `contain` and `outsideBounds`.

- A fast, universal `hit` method that handles collision testing and

  reactions (blocking and bounce) for all types of sprites. Use one collision method for

  everything: rectangles, circles, points, and arrays of sprites.

  Easy!

- A companion suite of lightweight, low-level 2D geometric collision methods.

- A loading progress bar for game assets.

- Make sprites shoot things with `shoot`. 

- Easily plot sprites in a grid formation with `grid`.

- Use a `tilingSprite` to easily create a seamless scrolling background.

- A `createParticles` function for creating all kinds of particle

  effects for games. Use the `particleEmitter` function to create a constant

  stream of particles.

- Use `scaleToWindow` to make the game automatically scale to its maximum size and align itself for the best fit inside the browser window. 

- Tiled Editor support using `makeTiledWorld`. Design your game in

  Tiled Editor and access all the sprites, layers and objects directly

  in your game code. It's an extremely fun, quick and easy way to make

  games.

- A versatile, `hitTestTile` method that handles all the collision

  checking you'll need for tile-based games. You can use it in combination

  with the any of the 2D geometric collision methods for optimized

  broadphase/narrowphase collision checking if you want to.

- Use `updateMap` to keep a tile-based world's map data array up-to-date

  with moving sprites.

- Create a `worldCamera` that follows sprites around a scrolling game

  world.

- A `lineOfSight` function that tells you whether a sprite is visible to   another sprite.

- Seamless integration with HTML and CSS elements for creating rich

  user interfaces. Use Hexi also works with Angular, React and Elm!

- A complete suite of tools for easily creating isometric game worlds, including: an isometric mouse/touch pointer, isometric tile collision using `hitTestIsoTile`, and full Tiled Editor isometric map support using `makeIsoTiledWorld`.

- A `shortestPath` function for doing A-Star pathfinding through tile based environments like mazes and a `tileBasedLineOfSight` function to tell you whether sprites in a maze game environment can see each other.

- Yes, Hexi applications meet W3C accessibilty guidelines thanks to the [`accessible`](http://www.goodboydigital.com/pixi-becomes-accessible/) property provided by the Pixi renderer (yay Pixi!)



<a id='features'></a>

### Hexi's modules



Hexi contains a collection of useful modules, and you use any of the

properties or methods of these modules in your high-level Hexi code.



- [Pixi](https://github.com/pixijs/pixi.js/): The world's fastest 2D WebGL and canvas renderer.

- [Bump](https://github.com/kittykatattack/bump): A complete suite of 2D collision functions for games.

- [Tink](https://github.com/kittykatattack/tink): Drag-and-drop, buttons, a universal pointer and other

  helpful interactivity tools.

- [Charm](https://github.com/kittykatattack/charm): Easy-to-use tweening animation effects for Pixi sprites.

- [Dust](https://github.com/kittykatattack/dust): Particle effects for creating things like explosions, fire

  and magic.

- [Sprite Utilities](https://github.com/kittykatattack/spriteUtilities): Easier and more intuitive ways to

  create and use Pixi sprites, as well adding a state machine and

  animation player

- [Game Utilities](https://github.com/kittykatattack/gameUtilities): A collection of useful methods for games.

- [Tile Utilities](https://github.com/kittykatattack/tileUtilities): A collection of useful methods for making tile-based game worlds with [Tiled Editor](http://www.mapeditor.org). Includes a full suite of isometric map utilities.

- [Sound.js](https://github.com/kittykatattack/sound.js): A micro-library for loading, controlling and generating

  sound and music effects. Everything you need to add sound to games.

- [Smoothie](https://github.com/kittykatattack/smoothie): Ultra-smooth sprite animation using 

  true delta-time interpolation. It also lets you specify the fps (frames-per-second) at which 

  your game or application runs, and completely separates your sprite rendering loop from your

  application logic loop.



Read the documents at the code repositories for each of these modules to find out

what you can do with them and exactly how they work. Because they're

all built into Hexi, you don't have to install them yourself - they

just work right out-of-the-box.



Hexi lets you access most of these module methods and properties as

**top-level objects**. For example, if you want to access the `hit` method

from the Bump collision module, you can do it like this:

```js

g.hit(spriteOne, spriteTwo);

```

But you can also access the Bump module directly if you need to, like this:

```js

g.bump.hit(spriteOne, spriteTwo);

```

(This assumes that your Hexi instance is called `g`);



Just refer to the module name using **lowerCamelCase**. That means you can

access the Smoothie module as `smoothie` and the Sprite Utilities

module as `spriteUtilities`.



There are two exceptions to this convention. You can access the Pixi

global object directly as `PIXI`. Also, the functions in the Sound.js module

are also only accessible as top-level global objects. This is was done

to simplify the way these modules are integrated with Hexi, and

maintain the widest possible cross-platform compatibility.



If you're a developer and would like to contribute to Hexi, the best

way is to contribute new and improved features to these modules. Or,

if you're really ambitious, propose a new module to the Hexi

development team (in this repo's [Issues](https://github.com/kittykatattack/hexi/issues),

and maybe we'll add it to Hexi's core!)



<a id='quickstart'></a>

Hexi quick start

----------------



To start working with Hexi quickly, take a look at the Quick Start

project in Hexi's [examples

folder](https://github.com/kittykatattack/hexi/tree/master/examples).

You'll find the [HTML container page here](https://github.com/kittykatattack/hexi/blob/master/examples/01_quickStart.html) and the [JavaScript

source file here](https://github.com/kittykatattack/hexi/blob/master/examples/src/quickStart.js). The source code is fully commented and explains how all everything works so, if you want to, you can just skip straight to that file and read through it. (You'll find the complied, ES5, version of the JavaScript file [in the `bin` folder](https://github.com/kittykatattack/hexi/tree/master/examples/bin).) 



The Quick Start project is a tour of all of Hexi's main features, and you can use it as a template for making your own new Hexi applications. Click on the image below to try a working example:



[![Quick start](/tutorials/screenshots/30.png)](https://cdn.gitcdn.xyz/cdn/kittykatattack/hexi/a1713aa19bdcc9a0c661e67d079a205d7c221917/examples/01_quickStart.html)



You'll first see a loading bar that shows you the percentage of files

(sounds and images) being loaded. You'll then see a spinning message that asks to you to tap on the screen to create cats. Cats will appear on the screen wherever you click with the pointer while music plays in

the background. (Oops, Sorry! I forgot to warn you about the music!) A text field rotates and counts the number of cats

you've created. The cats themselves move and bounce around the

screen, while scaling in size and oscillating their transparency.

Here's an illustration of what you'll see:



![Quick start illustration](/tutorials/screenshots/31.png)



Why cats? [Because](http://motherboard.vice.com/blog/toxo-terror-are-our-brains-controlled-by-cat-loving-parasites).



If you know how this Quick Start application was made, you'll be well on your

way to being productive with Hexi fast - so let's find out!



(Note: If you're new to game programming and feel you need a gentler,

more methodical, introduction to Hexi, check out the [Tutorials](#tutorials) section ahead. You'll learn how to make 3 complete games from scratch, and each game gradually builds on the skills you learnt in the previous game.)



<a id='thehtmlcontainer'></a>

### The HTML container



The only file you need to start using Hexi is

[`hexi.min.js`](https://github.com/kittykatattack/hexi/blob/master/bin/hexi.min.js). It has an incredibly simple "installation": Just link it to an HTML page with a `<script>` tag. Then link your main JavaScript file that will contain your game or application code. Here's what a typical Hexi HTML container page might look like:

```html

<!doctype html>

<meta charset="utf-8">

<title>Hexi</title>

<body>

<script src="hexi.min.js">