Game Creator Instruction Manual v0.6.3

Table
of Contents
About 1.1
Introduction 1.2
What Is Pixel Vision 8 1.3
Game Creator Features 1.4
Upgrading 1.5
Change Log 1.6
Using The Game Creator 1.7
Launching 1.7.1
The Workspace 1.7.2
Changing The Workspace Path 1.7.3
Pixel Vision 8 Games 1.8
Creating A New Game 1.8.1
System Templates 1.8.2
Editing Games 1.8.3
Inside A Game Project 1.8.4
Saving Games 1.8.5
Project Types 1.8.6
Loading Games 1.8.7
Working With Archived Games 1.8.8
Loading Data 1.9
System Data 1.9.1
System Colors 1.9.2
Color Maps 1.9.3
Sprites 1.9.4
The Sprite Builder 1.9.5
Fonts 1.9.6
Tilemaps 1.9.7
Tilemap Flags 1.9.8
Rendering To The Display 1.10
Clearing The Display 1.10.1
1
Rendering Sprites 1.10.2
Rendering Fonts 1.10.3
Rendering The Screen Buffer 1.10.4
Intro To Scripting 1.11
Demo Games 1.11.1
Lua Script Sample 1.11.2
Lua API 1.11.3
Included Tools 1.12
Navigation Toolbar 1.12.1
New Game Tool 1.12.2
File Picker Tool 1.12.3
Debug Tool 1.12.4
Credits 1.13
2
About
About The Game Creator Documentation

This documentation is currently a work in progress. Parts
of it may be incomplete or missing. Make sure to continue
to check for updates as each version of the Game Creator
is released.
The Game Creator is a full development environment for authoring 8-bit games and is built
on top of the open source Pixel Vision SDK framework.
It contains project management, asset creation, and coding/debugging tools. This all in one
solution enables complete end to end development allowing anyone to create desktop
games, share them and even build custom tools.
This documentation is designed to cover how to work with the Game Creator. It explores
everything you need to know about installing the Game Creator, making games and how the
tools work. You should check out the quick start guide before reading more of the in-depth
3
About
material covered in this documentation. Once you have read this documentation, you will be
ready to not only make Pixel Vision 8 games but also understand how to optimize them and
extend the editor by with custom built tools.
Latest version - v0.6.3 available at http://pixelvision8.com
4
Introduction
Introduction
My name is Jesse Freeman and ever since I turned my Nintendo on for the first time, I have
wanted to make games! While the technology has changed since the '80s, my desire to
make 8-bit games hasn't. I wanted a way to make authentic retro games but with modern
tools and workflows. This is how I came up with the idea for Pixel Vision 8.
I hope you enjoy using Pixel Vision 8 and making fun 8-bit games!
Sincerely,
Jesse Freeman (@jessefreeman)
5
What Is Pixel Vision 8
What is Pixel Vision 8

Pixel Vision 8's core philosophy is to teach retro game development with streamlined
workflows. It enables designing games around limited resolutions, colors, sprites, sound and
memory. It is ideal for game jams, prototyping ideas or having fun.
PV8 is also a platform that standardizes 8-bit fantasy console limitations built on top of the
open source Pixel Vision SDK. Developers can customize these restrictions to match actual
legacy hardware or create something new. The challenge of working within these confines
forces creativity and limits the scope. Pixel Vision 8 creations are expressions of ingenuity
that rise above their limitations.
6
Game Creator Features
Game Creator Features

Since Pixel Vision 8’s Game Creator is build on top of the open source Pixel Vision SDK, the
engine is completely modular. The underpinning of this system is exposed through an easy
to use Lua API allowing you to focus on making games without needing to modify any of the
core engine’s code directly. Pixel Vision 8: Game Creator offers the following features over
the core SDK:
The Workspace - A standardized location and workflow for loading, saving and editing
games.
Project Types - Support for several project file formats such as .pv8 (games), .pvs
(system templates), pvt (tools) and more.
Importers - Specialized importers for sprites, tilemaps, lua code and project metadata.
Booting and Loading - Allows a standardized system for loading games into memory
and editing them in the workspace.
Tools - Special API Bridges are exposed for loading, using and building custom tools to
edit games in memory.
Archiving - Games can be zipped up into archives to make them easier to run and
share with others.
7
Upgrading
Upgrading
The upgrade process should be straightforward. When the Game Creator detects you are
running a newer version, it automatically upgrades all of the core tools defined in the
bios.json file. Any changes to those tools overwritten. While the Game Creator moves old
tools into the trash during an upgrade, the trash is automatically set to empty on exit. If this
value is true, the Game Creator clears the trash when you shut it down.
One last thing, you should take a moment to understand how releases are numbered. The
Game Creator uses a standard versioning convention. For example, a build may look like
this v0.6.3 which denotes the major version, minor version, and patch number. Since the
Game Creator is still in alpha, the major version is zero. Each new stable release increments
the minor version. In between stable releases, are patches which help address bugs in the
previous release. Patch versions are not well tested and should be considered "use at your
own risk" builds until the next minor release is available.
If stability is a priority, stick to minor builds where the patch value is zero, 0.7.0a for example.
Once Game Creator reaches it is the first major version, v1.0.0, it is considered beta, and at
this point, all of the features are locked allowing development to shift focus on bug fixing and
optimizations. At v2.0.0 the Game Creator is a release candidate. At this point, work begins
on the next round of features to help move the platform forward.
8
Change Log
Change Log
The Game Creator is constantly be updated based on the new feature backlog, bugs that
need to be fixed and optimizing the underlying code base. Because of this, the goal is to
release new versions as often as possible. If you are new to the Game Creator or looking to
understand what has changed since the last release, you can find all of the changes below
broken down by the version number.
v0.6.3 Alpha
Fixed the save button, so it shows up correctly in the toolbar
Fixed the music tool so you can generate loops on games with 3 or fewer tracks (which
was throwing an array out of index error before).
Fixed color importer to now treats transparent colors in .pngs as the default PV8
transparency mask color (#FF00FF). You will notice this fix when previewing some
color.png files in the Display Tool.
Fixed the last used tool to work how it should. Now if you go from the editor to the game
and back you should automatically load the last used tool.
Optimized the Tilemap Tool's sprites. While this tool is still a WIP, I have been trying to
optimize how it loads tiles to speed that up a bit.
Deprecating editorBridge:LoadLib() which will be removed in v0.7.0a. Use

apiBridge:LoadLib() instead. Now any game can load an external library file from the
Game folder or the Workspace’s Lib folder.
Updated the Setting Tool. It now disables the game name if none exists. Also the
workspace path area is larger and there is now a dedicated volume/mute button.
Fix to the Tilemap Tool to display the correct scroll y value.
All new system templates which display basic instructions on how to modify a new
game file.
v0.6.2 Alpha
Rebuilt pre-loader logic to now display percentage and break up loading over steps.
Optimized tools to load faster based on new pre-loader logic.
9
Change Log
All new boot screen.
Added help messages to all of the tool's UI.
Added support to display line numbers for script errors.
Cleaned up Debugger Tool to now show icons based on event type.
Sprite Tool (pro only) now shows the sprites instead of fonts and other dynamically
generated artwork.
Sprite Tool (pro only) now supports exporting, reverting and clearing sprites.
Color Tool (pro only) now supports exporting, reverting and clearing colors.
Fixed issues where changing colors in the Color Tool cleared the display and wouldn't
show changes.
v0.6.1 Alpha
New tilemap preview tool (pro only).
Bug fixes and optimizations.
Cleaned up installer files and updated for v0.6.1a.
Created new Windows installers for free and pro executables.
v0.6.0 Alpha
All new file browser and system config tools.
New controller mapping tool.
New pro-tools for editing colors, sprites, sound effects and music.
Optimized rendered for better performance.
New API method calls for drawing sprites, text and more.
New editor bridges for colors, sprite, sound effects and music.
Bug fixes
New demo games showing off the controller input, drawing sprites, displaying a mouse
and playing back sound and music.
All errors are now displayed in a custom error screen.
New debug tool for display the game's log.txt file when running the engine.
10
Change Log
v0.5.0 Alpha
Create, play, edit, save and share PV8 games
Loading and error screens
Includes sample Lua game, RPG8, with source code and art
Includes tools for creating new games, saving/loading them and editing system settings
Full support for system colors, sprites and tilemap with collision
Open workflow allowing external pixel and code editors to modify games
No sound or music support in this build
11
Using The Game Creator
Using The Game Creator

The focus of the Game Creator is to streamline building and debugging Pixel Vision 8
games. The Game Creator leverages a unique workflow allowing you to use built-in tools as
well as external editors to create authentic 8-bit games. Also, the Game Creator is fully
extendable, allowing you to build custom tools on top of easy to use Lua Editor APIs.
Because of this hybrid approach, you can still use all of the tools you are comfortable with
like Photoshop, Aseprite, Sublime Text and more to quickly build games while leveraging the
built-in tools to make sure everything is working correctly. This unique workflow is possible
thanks to the way that Game Creator leverages its Workspace. The Workspace allows you
to work on game files while they are running in the editor, then refresh the game to preview
the changes.
Once you understand how to use Game Creator's Workspace, you can dramatically speed
up your Pixel Vision 8 game creation while taking advantage of modern editors and
workflows.
12
Launching
Launching the Game Creator

Pixel Vision 8: Game Creator works on Mac, PC and Linux. Simply run the installer or the
executable directly to open the development environment.
If you are running the Game Creator on Linux for the first time, you may get the following
error:
Simply right click on the version for your system, and set its permissions to run as an
executable like so:
13
Launching
By default, Pixel Vision 8 runs in window mode. You can resize the window to fit your needs.
A full-screen toggle is planned for a future release.
14
Launching
Once the Game Creator is launched, it will boot and attempt to run a game if one exists. If
no game is present, Game Creator will boot up the editing environment.
15
Launching
If you decide to leave the editing environment when no game is present, you’ll see an error
screen.
16
Launching
Next, we will learn about the workspace as well as how to load games and tools.
17
The Workspace
The Workspace
The Game Creator makes a Workspace folder in a shared location on your computer. By
opening up the Workspace folder, you can work directly on a game’s files in your editor of
choice. To get the path, you can to enter editor mode by pressing control 1 on the keyboard.
Once in edit mode, you can access the settings tool from the top navigation.
Once you load up the settings tool, you should see a screen like this that shows you the path
to where the workspace folder exists on your computer.
You can change this path to anywhere on your computer.
18
The Workspace
There are buttons to reset the path, copy the existing path or paste in a new path. To
navigate to the default location, select the copy button and paste the path it into the file
browser on your computer. The path on my Windows computer is:
C:/Users/Jesse Freeman/AppData/LocalLow/Pixel Vision 8/GameCreatorFree/
Yours should be similar with a different user name.
Inside the Workspace folder are four directories: Archive, Game, Lib, and Trash.
The Archive is where the Game Creator stores finished games, tools, and systems. The
Game folder is for any game the engine is currently running, or you are editing. This
directory is persistent and only replaced when you load a new game. Since this folder is
persistent, you to continue working on a game across different sessions. The Lib folder
contains Lua scripts shared across different games or tools. Trash contains files that ready
to be deleted. By default, the Game Creator empties the trash when you exit.
19
The Workspace
You can override the default system path by pasting in the path where you want to store
your workspace on your computer. Game Creator confirms that the path is valid before
creating the new Workspace folder along with all the required projects. Contents inside of
the Game, Lib or Trash folder are not copied over when creating a new workspace.
20
Changing The Workspace Path
Changing the Workspace Path

In addition to using Game Creator’s Settings Tool, you can manually override the default
system path by hand. Sometimes it is useful to change this if Pixel Vision 8 fails to load
manually or the file becomes corrupted. The Game Creator stores the workspace path inside
of the bios.json , at the root of the default, save location on your computer.
Inside it, search for workspacePath in the JSON and replace it with your path:
You can use forward slashes regardless of operating system. If you want to use backwards
slashes on Windows make sure you escape them.
You must restart Pixel Vision 8 if it is already running. Once reloaded, the Game Creator
loads the new path as long as it is valid. If the directory is empty, the Game Creator
generates a new Workspace.
21
Changing The Workspace Path
When Pixel Vision 8 boots up, it analyzes the Workspace folder to make sure all the folders
it needs exist. Also, it attempts to restore any of the core tools and built-in game examples
you may have deleted from the Archive folder.
By changing the path of the workspace by hand or with the Settings Tool, you can have
multiple workspaces on your computer, as well as keep them under version control.
However, PV8 can only work from a single workspace at a time.
22
Pixel Vision 8 Games
Making Pixel Vision 8 Games

Pixel Vision 8 games are designed to run with the Pixel Vision SDK. This open source SDK
is written in C# but also supports Lua games. While you could easily build PV8 games
natively, the Game Creator streamlines this process. It also provides a standard file format,
loading mechanism, and asset pipeline.
The Game Creator packages up PV8 games in a zip format. Based on the use, the file has a
unique extension. Games are saved as .pv8 files while tools and system templates end in
.pvt and .pvs respectively. The Game Creator manages setting up new games from
scratch as well as archiving them when you are done making changes. These archive files
can also be shared and run by other Game Creator users.
Understanding how the Game Creator manages games inside of the Workspace is essential
to making your Pixel Vision 8 games that others can play.
23
Creating A New Game
Creating A New Game

When you load up Game Creator for the first time, you are taken directly to the New Game
Tool.
You can create an empty game project by clicking on the new game button at the bottom of
the screen.
24
Creating A New Game
Once pressed, the Game Creator copies the default system template over to the Game
folder. When the Game folder is ready, Game Creator automatically switches back over to
play mode presenting you with a new game file and some instructions on how to edit it.
25
Creating A New Game
At this point, you are ready to start coding your game. If for some reason there was a
problem loading a game, the Game Creator shows an error with instructions on what to do to
fix the problem.
26
Creating A New Game
You can always switch back to edit mode by pressing Ctrl + 1 . By default, the New Project
Tool should automatically load.
Before you create a new game, you must decide which system template you want to use.
27
System Templates
System Templates
Under the hood, the Pixel Vision 8 engine is broken down into several "chips" that control
how the engine behaves. The chip system is modular, allowing you to define each chip’s
limitations. When creating a new game, you can customize system limitations by selecting
one of the pre-configured system templates:
The specs panel represents a summary of a system template’s limitations. It is broken down
into six aspects that map over to Pixel Vision 8’s built-in chips. Here are the main chips
groups that make up a working system: resolution, colors, sprites, tilemap, sound SFX, and
music. Together these limitations help define what you can and can’t do when making PV8
games and tools.
Here is a breakdown of each property:
Resolution
W Width The width of the screen’s resolution.
H Height The height of the screen’s resolution.
28
System Templates
Colors
T Total Total number of colors the system supports.
PS Colors Per Sprite Total colors per sprite.
Sprites
T Total Sprites The total number of sprites allowed in the memory.

Maximum The maximum number of sprites the display can render in a
Max
Sprites single frame.
Tilemap
W Width The width (in tiles) of the tile map.

H Height The height (in tiles) of the tile map.
Sound
CH Channels The total number of channels on which the system can play sounds.
The total number of sound effects the system can store in its
T Total
memory.
Music
TR Tracks The total number of tracks the music chip can use to play back sounds.
T Total The total amount of music data the system can store in its memory.
29
Editing Games
Editing a Game
When you launch the Game Creator, it attempts to load the files in the Game Directory. Here
we have created a new game and can see the default message letting us know the game
works and is ready to be modified.
All of the game's files are inside of the Workspace’s Game directory.
30
Editing Games
Pixel Vision 8 game files can be modified by external editors. This allows you to use
Photoshop, Aseprite, or any pixel editor for creating sprites and tilemaps. Likewise, feel free
to use any code editor for working with a game's Lua and JSON files.
At any point, you can switch back into the Game Creator’s edit mode by pressing Ctrl + 1 .
By default, the New Project Tool should automatically load.
31
Editing Games
If you were using a different tool, that one would reload instead of the default New Game
Tool allowing you resume what you were doing before running the game. Once in edit mode,
you can always return to play mode by pressing the play button or using the Ctrl + 1
keyboard shortcut.
If you are playing a game and want to see any changes you have made externally, you can
also use Ctrl + 4 to force the game to reload without entering edit mode. If your game fails
to load, the Game Creator shows an error screen to help you debug the issue.
Once you have fixed the error, simply reload the game. All errors and print statements are
visible in the Debugger Tool. You can open this tool by switching to edit mode and selecting
it from the toolbar.
The Debugger Tool maintains the log file while the Game Creator is running.
32
Editing Games
When you exit, the Game Creator deletes the log file and all of the contents of the Tmp
directory. You can access the log file directly from Workspace's Tmp folder.
Since it is a text file, you can open it in any external text editor.
33
Inside A Game Project
Inside a Game Project

A game is simply a collection of files that PV8 loads into its memory. Each of these files has
a specific purpose in the project. Here are the supported files that can go inside of a zipped
up game:
Name Ext. Description

code .lua This Lua file, which contains all the code to run the game.
color- The color map represents a file that can be used to match up colors
.png
map in the sprite.png to the order in the colors.png.
The colors image contains all the system colors used for rendering.
colors .png
These colors should be 1x1 pixel for each color.
The data file represents chips and their settings that make up the
data .json
fantasy console the game should run on.
This is a default font to be used at run-time. It works similar to the
font .png sprite.png, except the order is based on ASCII code. It starts at 32
(spaces) and supports any number of characters you add.
This is a metadata file that describes the contents of the game’s zip
info .json project. It is used to simplify editing things like the game’s name
without having to dig through the data file.
This .png contains all of the sprites the game uses. It is
sprites .png automatically loaded and cut up into 8x8 sprites based on the order
of images in the file.
This represents a map to be used in the game. It’s cut up in a
similar way to the sprites.png, except each sprite in the tile map is
tilemap .png compared to the sprites in the memory. If found, the ID is stored
internally. If the sprite doesn’t exist, it’s added to the sprites in the
RAM, assuming there is enough memory space.
This .png represents collision data in the tile map. It uses a

tilemap-
.png grayscale color system to identify what ID the flag represents. By
flags
default, it supports 16 colors or flags.
Pv8 will ignore any additional files in a project. In order for a game to load correctly, you
need at least the following files:
1. data.json
2. code.lua
3. info.json
34
Inside A Game Project
All the other files are optional. Files like sprites and tilemap are automatically generated
when saving a project; they will simply be empty .pngs.
35
Saving Games
Saving Games
Before saving a game, you should rename it. The Settings Tool allows you to rename game
projects without having to modify the info.json file manually.
Here you can modify the game's name, its type as well as the maximum size for the game to
be. 8-bit games had specific limitations around how big they could be. This value is initially
set by the system template you chose, but you can also increase or decrease this value
based on your needs.
Whenever you make changes to your project's settings you should hit the save button at the
bottom of the tool.
This does not save the game but instead writes the changes to the game's data file. In the
case of renaming a game, the data is writing into the info.json.
36
Saving Games
After you have named your game, you are ready to save it. You do this while in edit mode by
selecting the save button in the toolbar.
Once saved, the button is disabled until the Game Creator detects a change inside of the
Game folder.
Saving a game copies it over to the Archive folder. An archive contains the zipped contents
of a game. The Game Creator uses the name of the game for the archive, and the .zip
extension is modified based on the game's type.
37
Saving Games
This means that you can unzip any game in the Archive folder manually by changing the
extension back to .zip and extracting the contents. Feel free to go through any of the
included tools, demos or system template files to see how they work. Archiving the file is
also useful for sharing with others. You can install new games by adding them to your
Archive folder.
If there is an existing game with the same name in the Archive folder, it is time stamped and
moved into the Trash folder.
The Trash folder is emptied automatically whenever you shut down the Game Creator.
38
Saving Games
You can stop the Game Creator from deleting trash in the Settings Tool.
39
Project Types
Project Types
Pixel Vision 8 games are zip files with a custom extension. Each extension type tells the
engine how to handle it. The extension simply tells PV8 how to load the file and unzip it. You
can change your project type at any time by selecting a file extension in the System Setting
Tool.
Here is a breakdown of all the supported extensions and how they work:
40
Project Types
Type Ext. Description
A game represents all the code, settings and art needed to run.
Game .pv8 This is considered the final product and is ready to be shared with
others.
A tool is a game that runs with specific ties to the editor API. The
Tool .pvt engine can load a tool alongside to a game allowing you to edit the
currently loaded game.
A system template is a base project to start making a game on top
of. This could just be the .json system specs, or it could also
System include code, art, etc. There are five base templates, but you can
.pvs
Template always create your own. Contents of the template are simply
copied to the Game folder in the workspace and are not linked
back to the original template to give you a fresh start.
When loading an asset pack, the contents of the project are simply
Asset copied over into the current Game folder inside the workspace.
.pva
Pack This allows you to share art resources, sounds, and music between
projects.
All of the above extensions are technically games to PV8. They share the same file structure
inside the zip. The extension simply tells PV8 how to load the file and unzip it.
41
Loading Games
Loading Games
To load a game, go into edit mode by hitting Ctrl + 1 and then click on the folder icon in
the toolbar.
From here, you can pick the game you want to load.
The File Picker Tool helps organize all the games in the Workspace's Archive folder. By
default, the file picker displays games ending in Pixel Vision 8's .pv8 extension. You can
change the extension filter to show other types of files that the Game Creator supports.
42
Loading Games
Once you have found the file, you want to load. Select it and click the open button at the
bottom of the tool.
The File Picker Tool replaces the contents of the Game folder loading a new game. Make
sure to save the current game before loading a new one. Game Creator does not move files
inside of the Game folder to the trash. Also, if for some reason a project does not load, you
get an error.
You may need permission errors when files in the Game folder are open in an external
application. When this happens, it is best to close out of any external editors and manually
delete the Game folder.
43
Working With Archived Games

Pixel Vision 8 was designed to teach people how to create 8-bit games. With that in mind,
the Game Creator's file format is not only easy to share with others but also easy to open up
and view its contents. Game files, including system templates and tools, are simply .zip files.
You can easily open any of the ones included with the Game Creator by changing the
extension and unzipping it. Let's look at how we can add new games to Game Creator as
well as how to view their contents.
The most common type of file is going to be a .pv8 which are a Pixel Vision 8 game.
Pressing the Save button in the toolbar converts the contents of the Game directory into a
.pv8 by default.
Once the contents of the Game directory are packaged up, it is copied over to the Archive
directory.
44
If a file with the same name exists, the previous version is moved into the Trash directory
and renamed with a timestamp.
If you download a game from somewhere else, you can simply put it into your Archive
directory.
45
Any supported files added to the Archive folder automatically show up inside of the File
Picker Tool.
The Game Creator includes a collection of demo games, tools and more based on the
version you own. You are encouraged to look at the included files to learn more about how
to structure and organize your projects. To do this, simply go into the Archive folder and find
the demo game you want to open. Simply append .zip to the end of the name and unzip it.
46
If you want to run a game manually, you can always select the contents of a unzipped game
and copy them over to your Game directory.
One thing to keep in mind is that any developer or player can explore the contents of your
game as well. Feel free to add a license file to your game letting others know what they can
and can't do with the code and artwork.
As you look through some of the files included in the Game Creator, game demos are fully
open source while tools simply allow you to modify them but limit sharing publicly with
others.
47
48
Loading Data
Loading Data
When the Game Creator attempts to load a game from the Archive, the contents are copied
over to the Game directory, and each file loads in a specific order. Knowing this order is
important to understand how a game is prepared to be played by the engine. Here are the
steps the Game Creators importer following:
1. System Data
2. Lua Code
3. System Colors
4. Color Map
5. Sprites
6. Tile Map
7. Tile Map Flags
8. Fonts
9. Metadata
All the data in a game project is loaded at run-time and parsed when a game first loads.
After the game is running, changes made to the files require the game to reload and each
file reimported. You to work on a project with an external editor while it is running then hit
refresh Ctrl + 4 to see your modifications.
49
System Data
System Data
The data.json file is perhaps the most important file in the load process. It contains all of
the chips, a core component of the engine, which define the specs for configuring PV8 to
play the game. Here is a breakdown of the main chips built into the engine:
Since the data.json contains information on which chips the system should use, as well as
properties like the system colors, number of colors per sprite and more, this file defines how
the actual engine and the rest of the files are loaded into memory.
Here is a sample of what a typical data.json file looks like:
50
System Data
{
"PixelVision8.Chips.ColorChip":
{
"pages":1,
"supportedColors":4,
"transparent":"#FF00FF"
},
"PixelVision8.Chips.SpriteChip":
{
"spriteWidth":8,
"spriteHeight":8,
"pages":4,
"cps":4
},
"PixelVision8.Chips.DisplayChip":
{
"wrapMode":1,
"width":160,
"height":144,
"autoClear":1,
"maxSpriteCount":40
},
"PixelVision8.Chips.TileMapChip":
{
"columns":32,
"rows":30,
"totalFlags":16
},
"PixelVision8.Chips.ScreenBufferChip":
{
"backgroundColor":-1,
"viewPortWidth":256,
"viewPortHeight":240
},
"PixelVision8.Chips.SoundChip":
{
"totalChannels":4,
"sounds": [
...
]
},
"PixelVision8.Chips.MusicChip":
{
"totalTracks":3,
"notesPerTrack":127,
"songs":[
...
]
},
"PixelVision8.Chips.LuaGameChip":
{
"maxSize":128,
51
System Data
"saveSlots":8,
"savedData":{
...
}
}
}
Each block of data in the .json file defines a chip for the engine to initialize and its settings.
Let’s take a look at the SpriteChip and how it gets serialized. The first line of the JSON
object is the engine’s qualified class name:
"PixelVision8.Chips.SpriteChip": {
When this parses, the ChipManager automatically creates an instance of this class. Next are
properties that can be configured on the chip. Only a handful of properties can be
configurable in the .json file. Here are the four main properties of the SpriteChip :
"spriteWidth":8,
"spriteHeight":8,
"Pages":4,
"cps":4
After the chip is deserialized, the JSON properties are passed to a special method that all
chips share and the values for each property are set. In this chip, you can change the size of
sprites system-wide, as well as the memory size where sprites are stored. By default, sprite
RAM can store 16 columns and 16 rows of sprites for a total of 256 sprites per page.
While you can manually change values in this file, it’s best not to do so unless you know
exactly what you are doing. The underlying engine that runs PV8 is incredibly open and
allows for all kinds of customization. The Game Creator, however, has a lot of restrictions on
top of it to better adhere to the predefined limitations of the fantasy consoles it attempts to
emulate. Use caution when modifying this file.
52
System Colors
System Colors
Each system template includes a set of default colors inside of a colors.png file. This file
represents all of the colors availble at runtime and contains one color per pixel. The Game
Creator reads through each color and loads it into the ColorChip when loading a game.
The color importer scans the PNG’s color data a pixel at a time, starting in the upper-left
corner and ending in the bottom right, saving each color until reaching the color limit. You
can always change the supportedColors value in the data.json file or through the Display
Tool.
To create your color.png file by hand, simply create a single line of pixels or lay them out in
a grid. Here is an example of how the color importer traverses a grid of pixels inside of a
color.png file:
Any colors over the supportedColors value will be ignored. The order of the colors in the
PNG will match how they are stored in memory. Once you know their ID, you can reference
them as needed like setting the background color value.
The Display Tool is designed to make it easier to work with a game’s colors:
53
System Colors
This tool allows you modify any of the current colors that have been loaded and change the
limitation of the Color Chip. You can also export a new color.png file to the Game directory
when you want to save your changes.
One important thing to note about a game’s colors is that they are used to read the sprite
and tilemap data. If a color does not exist in the system before importing sprites and tilemap,
it may be missing in the final sprite data saved to memory. Missing color data also impacts
how sprites load, their ID in memory and if they even show up. It is critical that you always
provide a complete set of system colors used by your game's artwork for it to load properly.
54
Color Maps
Color Map
The color map allows the engine to better understand how to index sprite and tilemap PNGs.
Without a color-map.png , the engine automatically attempts to use the system colors as the
index. The color map allows you to work with any set of colors you want when making your
game’s artwork and then re-map them to the system’s default colors. Let’s take a look at a
few sprites and how their colors are indexed when imported:
Here you can see that these sprites contain four colors, not including transparency which is
represented as magenta. They could work well with a Game Boy color palette, but that
system uses four shades of green:
To fix this, we can create a color map that has the native sprite colors in the same order as
the system colors, like this:
Now when the sprites are loaded up in memory, they will automatically use the correct
system colors:
Here is an example of the color mapper being turned on and off:
55
Color Maps
As a best practice, you should always design your sprites in shades of gray and include a
color-map.png . That way, the engine knows how to correctly parse your sprite and tilemap
data since they both share the same graphic import parser. If the importer finds a color-
map.png file, it is used to process any sprites or tilemap files loaded next.
56
Sprites
Sprite Data
When games load, the engine looks for a sprite.png to process. The sprite.png can be used
to load sprite data into memory and is made available as an option for those using external
image editors to work on their graphics. The .png is cut up into 8x8 chunks of pixel data,
which represent individual sprites in memory. Since sprites are simply collections of
references to color IDs, the system attempts to match those colors to what exists in the
system already or to a color map. One the importer is done converting a sprite's pixel data;
the Sprite Chip stores the compressed data in a memory slot which becomes its ID.
Importing Sprites
In addition to processing the sprite.png image and converting it to indexed color data, the
Sprite Chip also optimizes the data by only storing unique sprites. Let’s take a look at a
sample sprite.png from the New Game Tool. Here you can see we have two UI screens laid
out next to each other as a 512 x 240 pixel sprite.png image. If the Sprite Chip imports all of
the sprites as is, we end up 1,920 sprites:
Since PV8 only supports 8 x 8 pixel sprites, the importer works through the sprite.png file,
starting in the upper left-hand corner, converting each 8 x 8 pixel block of data into a format
the Sprite Chip can store. As it works through the pixel data, the importer removes repeating
sprites to optimize the amount of space the Sprite Chip has left. You can see how this works
by examining what the Sprite Chip now contains:
57
Sprites
The importer automatically optimizes the sprites.png leaving us with 602 sprites, which is a
68% reduction. It is also important to note that transparent pixel data is ignored and
converted to the system’s default mask color which is magenta (#FF00FF). PV8 does not
store transparent colors. Any colors not available to the system, including transparency, is
simply not drawn to the display. However, you can use transparent colors when importing
sprites as long as your understand they will be masked when being used inside of the
rendering engine.
58
Sprites
Colors Per Sprite

While the Sprite Chip imports each sprite, it analyzes the total number of colors and
compares this to what the chip can display. An 8 x 8 pixel sprite can have a maximum of 64
unique colors, but older 8-bit systems are unable to display that many colors at once. To
simulate this, the Sprite Chip has a property that represents the total colors per sprite, or
CPS for short. While this value can be increased or decreased based on your needs, the
reduced number of sprite colors is a hallmark of classic 8-bit systems and their memory
limitations around drawing sprites to the display.
While processing sprites, the importer calculates if each one contains more colors than are
allowed. When this happens, additional colors are converted to the internal transparency
color and forcing the sprite to adhere the Sprite Chip's CPS limitation. Here is an example of
how this works with an 8 color sprite:
If we reduce the CPS to 3 you begin losing pixel data:
Understanding how CPS works is critical to importing pixel data into the Sprite Chip.
Sprite Memory Pages

Keep in mind that the Pixel Vision 8 also places limits on the number of sprites it can store in
memory. While technically the engine can support any .png that is divisible horizontally and
vertically by eight, it helps to optimize your art based on sprite pages, which is how the
internal system stores and calculates the total sprites available.
A single sprite page is 128x128 pixels, which contains 256 sprites. When you are configuring
the system, you can define how many pages the Sprite Chip supports. The maximum
number of pages is eight, with a potential total of 2,048 sprites. Here is a breakdown of how
sprite pages scale:
59
Sprites
Pages Total Sprites
1 256
2 512
3 768
4 1,024
5 1,280
6 1,536
7 1,792
8 2,048
One way to help optimize your sprites is to store them in page blocks before importing. Let's
look back at the earlier example with the imported New Game Tool sprites. If we were to
export the sprites from the Sprite Chip, we would end up with a 256 x 768 image:
60
Sprites
Here you can see how each page of sprites is broken up. Since the importer works from the
top left of the sprite.png to the right as it traverses each row of pixels, this is the most
optimized way to store sprites ready to be imported.
When building a game, don't focus on optimizing your sprite.png at first. While you may see
slower load times, simply work on your sprites in a way that makes sense to you. Before
sharing the game, simply dump the Sprite Chip's memory to a png file after importing your
original sprite.png, and you can use that as the optimized file. Here is an example of how I
organize the sprites inside the tool files:
61
Sprites
As you can see, I keep two sprite files. The first is the sprites.original.png which is ignored
by the importer but allows me to still work with sprites in my image editor of choice. For
running the game, I use the optimized file as the main sprite.png.
Working With Large Sprites

Even though Pixel Vision 8 can only support rendering 8x8 sprites, you can still use larger
sprites in your game. To do this, you will need to combine those sprites at run-time. Let's
take a look at some sample UI:
Here you can see we have the pagination buttons. In this example, we have a 5 x 2 grid with
a total of 10 sprites:
62
Sprites
Some of these sprites repeat or are empty, which helps cut down on the total number of
sprites that are stored in memory. You will see that we have six unique sprites, but we still
need nine sprites to render, ignoring the one empty sprite in A2.
Just keep in mind that the system has a limit on the number of sprites it can draw to the
display, so the larger your sprites, the less you may have to display other elements in the
end. You can also leverage the tile map to gain an additional area to render larger tiles that
don’t need to move around the screen.
63
The Sprite Builder
The Sprite Builder

While the Game Creator offers several features that help make importing 8 x 8 sprites
easier, some games require larger sprites. Built into the Game Creator is a feature which
helps streamline converting lots of smaller 8 x 8 sprites into larger collections of sprites you
can use at run-time. Coupled with some built in APIs for rendering multiple sprites at once, it
is possible to take advantage of this particular workflow in your development.
To get started using the Sprite Builder, simply create a new folder in the root of your
Workspace called SpriteBuilder.
Once you have created this folder, a new button appears at the bottom of the Sprite Tool's
action bar.
64
The Sprite Builder
The Sprite Builder folder allows you to store large sprites and import them into your game.
The Sprite Builder tool looks at the makeup of each png inside of the folder and attempts to
match every 8 x 8 block of pixels to an existing sprite. The results are converted into Lua
tables and injected into your code.lua file. Let's take a look at how this works.
Here we have a collection of sprites that make up all of the artwork for our game.
65
The Sprite Builder
These were designed and laid out in Photoshop. Since the game is still in development, it is
easier to work with all of the sprites like this. As one large image they are easy to modify and
update as needed. But when we save this to the Game folder as our sprites.png file, the
importer optimizes them in memory.
Each sprite gets a unique ID, and we could use this ID to rebuild them in the game. Our
player, for example, is made up of 6 sprites.
66
The Sprite Builder
While we could simply find each ID and manually draw them to the display, over time this
workflow breaks down. First, the order of sprite may change depending on alterations made
to the underlying sprites.png image. Second, finding the IDs of all the sprites by hand is
time-consuming. Finally, managing all of these resources becomes frustrating, and the goal
of Game Creator is to make games, not manager artwork!
To leverage the Sprite Builder, we need an image. We'll isolate the first animation for the
player and put that into the SpriteBuidler folder.
67
The Sprite Builder
Now back in the Sprite Tool, we can press the Build button, and Sprite Builder analyzes the
contents of the SpriteBuilder folder and generates sprite IDs for use in the code.lua file.
Let's take a look at the output:
Here you can see we now have a new Lua table named after the png in the SpriteBuilder
folder. We also get the size of the sprite, the IDs and a reference to the total amount of
unique sprites. If we wanted to draw this sprite, we could simply call apiBridge:
DrawSprites() and pass in the data like so:
apiBridge:DrawSprites(playeridle.spriteIDs, 0, 0, playeridle.width, false, false, true

, 0)
The DrawSprites() method allows you to render larger sprites that are laid out in a grid.
Simply give this method the sprite IDs and the width to render any size sprite you want. Just
keep in mind that each sprite ID counts towards your maximum sprites on the screen cout
defined by the system’s specs.
68
The Sprite Builder
At this point, you can probably see the potential of the Sprite Builder tool. Just dump
collections of images into this folder and auto generate data for all of your larger sprites.
Here I am using Photoshop's slice feature to cut up each sprite, and I can use Save for Web
to generate all the png files I need.
This is what Photoshop exports to the SpriteBuilder folder.
69
The Sprite Builder
Once I have all the file in the SpriteBuilder folder, I can inject the data and reference my
sprites by their name instead of the ID.
70
The Sprite Builder
If anything changes in the source image, I can re-export out all of my images to the
SpriteBuilder folder and regenerate the data. Since my code references the sprite name
instead of the ID, my code continues to work as I modify all of the artwork during
development.
The Sprite Builder is a very powerful tool and was used to generate all of the sprite data for
each tool. Feel free to open up any of the tool projects, and look at the generated sprite data
at the top of each code.lua file for a better idea of how to leverage this feature in your own
game.
71
Fonts
Fonts
The Game Creator also supports for loading sprite fonts into memory. The characters of the
font come from any file ending in .font.png . You can even have multiple fonts in a single
game.
These files are similar to the sprites.png . Each character can be 8 x 8 and goes into any of
the GameChip 's free memory slots. This means that you should always allow extra space in
your SpriteChip to store fonts. In future versions of the Game Creator, a special font tool
will help make this shared storage situation clearer.
Each character in the .font.png file should match up to their ASCII values. The parser
starts at 30, which represents an empty space. Each character after that goes up in value.
Here is a chart showing the breakdown of the default supported characters:
DEC Symbol Description DEC Symbol Description

32 Space 80 P Uppercase P
33 ! Exclamation mark 81 Q Uppercase Q
34 " Double quotes 82 R Uppercase R

35 # Number 83 S Uppercase S
36 $ Dollar 84 T Uppercase T
37 % Procenttecken 85 U Uppercase U
38 & Ampersand 86 V Uppercase V
72
Fonts
39 ' Single quote 87 W Uppercase W

40 ( Open parenthesis 88 X Uppercase X
41 ) Close parenthesis 89 Y Uppercase Y
42 * Asterisk 90 Z Uppercase Z
43 + Plus 91 [ Opening bracket
44 , Comma 92 \ Backslash
45 - Hyphen 93 ] Closing bracket
Period, dot or full

46 . 94 ^ Caret - circumflex
stop
47 / Slash or divide 95 _ Underscore
48 0 Zero 96 ` Grave accent
49 1 One 97 a Lowercase a
50 2 Two 98 b Lowercase b
51 3 Three 99 c Lowercase c
52 4 Four 100 d Lowercase d

53 5 Five 101 e Lowercase e
54 6 Six 102 f Lowercase f
55 7 Seven 103 g Lowercase g
56 8 Eight 104 h Lowercase h
57 9 Nine 105 i Lowercase i
58 : Colon 106 j Lowercase j

59 ; Semicolon 107 k Lowercase k
60 < Less than 108 l Lowercase l

61 = Equals 109 m Lowercase m
62 > Greater than 110 n Lowercase n

63 ? Question mark 111 o Lowercase o
64 @ At symbol 112 p Lowercase p
65 A Uppercase A 113 q Lowercase q

66 B Uppercase B 114 r Lowercase r
67 C Uppercase C 115 s Lowercase s

68 D Uppercase D 116 t Lowercase t
69 E Uppercase E 117 u Lowercase u
73
Fonts
70 F Uppercase F 118 v Lowercase v
71 G Uppercase G 119 w Lowercase w
72 H Uppercase H 120 x Lowercase x
73 I Uppercase I 121 y Lowercase y

74 J Uppercase J 122 z Lowercase z
75 K Uppercase K 123 { Opening brace
76 L Uppercase L 124 | Vertical bar
77 M Uppercase M 125 } Closing brace

Equivalency sign -
78 N Uppercase N 126 ~
tilde
79 O Uppercase O 80 P Uppercase P
While you can arrange your .font.png character sprites in any 8 x 8 grid-based layout, it is
best practice to follow this template:
While the default template only supports the standard English character set, special
characters can also be added to the template; they will be parsed and assigned an ASCII ID
exactly like the main set of characters.
74
Tilemaps
Tilemap
The tile map works similar to the sprite.png. Since tile maps are simply compressed data
structures representing sprite IDs in a grid, the image is cut up into 8 x 8 tiles and that pixel
data is compared to existing sprites in memory.
For the tools, they have a resolution of 256 x 240 pixels, which equates to 32 sprites
horizontally and 30 sprites vertically for a total of 960 sprites rendering in the tile map at one
time. Here is an example tilemap.png from the New Game Tool:
The tilemap can actually be larger than the visible screen. There are limits on the number of
columns and rows based on each system.
75
Tilemaps
Make sure to pay attention to those dimensions when creating new games. Tilemaps can be
any size within those boundaries.
When a tilemap.png is loaded up into memory, it is cut up into 8 x 8 pixel sprites just like
the sprites.png . The first position 0,0 is located at the upper left-hand corner of the map.
You can not have negative tile ID positions. Each tile is analyzed and, when a match is
found, it is stored in the tile map. This allows you to design complex maps that compress
easily based on the number of repeating tiles used. Tiles that are not present in sprite
memory are added, assuming there is still room to store them. This allows you to separate
artwork between the sprites.png and tilemap.png if that makes organizing assets easier.
Since they are all combined into sprite memory in the end, the game won’t know the
difference.
76
Tilemap Flags
Tilemap Flags
The tilemap-flags.png represents tile collision data. Each tile can be assigned a specific
color, and that color corresponds to an ID number flag. The PNG is read in 8x8 pixel chunks,
but the first pixel color is used and the others are ignored. When a flag color is detected, the
flag’s value is set. Here are the supported flag colors and their corresponding values:
Flag 0 Flag 1 Flag 2 Flag 3 Flag 4 Flag 5 Flag 6 Flag 7

#000000 #101010 #202020 #303030 #404040 #505050 #606060 #707070
Flag 8 Flag 9 Flag 10 Flag 11 Flag 12 Flag 13 Flag 14 Flag 15

#808080 #8f8f8f #9f9f9f #afafaf #bfbfbf #cfcfcf #dfdfdf #efefef
The best way to create a collision mask is to overlay the flag colors on the tile map and
export them without the tiles in the background so they match up:
It’s important to note that the tile-map.png needs to match the exact dimensions of the
tilemap.png or they will not work.
77
Rendering To The Display
Rendering To The Display

Pixel Vision 8 is designed specifically to render pixel data to the screen. The way that the
Display Chip does this differs greatly from modern rendering techniques. It is the job of Pixel
Vision 8's importers to convert sprite's color data into color index values. Each color ID
reference to a color in the Color Chip's memory.
By converting pixel data into colors IDs, Pixel Vision 8 can optimize storing graphic data in
memory. This technique was popular for 8-bit consoles with limited resources. Another
advantage of storing pixel data like this is being able to dynamically replace the color of a
given ID at run-time letting developers recolor sprites at run-time. It is the job of the Display
Chip for making this possible.
78
Clearing The Display

When you create a new project without any code in it, the display simply shows the
background color. This default color is magenta (#FF00FF). This color is displayed
whenever a color value is out of range.
Since the background color is set to -1 by default, you are not able to display much else. You
can always override the default background color in the Display Tool.
79
Now if you refresh the game, you can see the new color. However, it is important to note that
the display is not rendering anything new. You have to tell the renderer it needs to display
pixel data. The easiest way to do this is by calling apiBridge:Clear() .
80
Not only does this method display the current background color, it also removed the previous
frame's pixel data. If you were to render a sprite to the display and move it without calling
clear, it would ghost.
You can update the background color at any time, and the next time the engine calls Clear(),
the color reflects the change. Try adding this to your Update() method:
apiBridge:ChangeBackgroundColor(math.random(0, 3))
81
Now when you refresh your game, the background will randomly change between the first 3
colors. Understanding how to correctly clear the display is critical to creating clean render
logic for your game.
82
Rendering Sprites
Rendering Sprites
Once you have defined the background color, you can draw sprites to the display via the
apiBridge:DrawSprite() method. This method needs to know the sprite ID. Then it requires
an x and y position for where to place the sprite on the screen. By default, the display wraps
sprite so if-if you draw a sprite to an x or y position past the display’s dimensions it
appears on the opposite site of the screen.
You can disable wrapping by changing the apiBridge.wrapMode property to false. Generally,
should set this property during the Init() stage of your game. There is also a slight
performance hit when pixel wrapping is activated. The performance hit is nominal for small
numbers, but it is best to keep your sprite’s x and y position within the value of the
screen’s display to optimize rendering.
When rendering a sprite to the display, there are several optional boolean values you can
supply for flipping the sprite horizontally or vertically. You can preview how these affect your
sprites in the Sprite Tool.
83
Rendering Sprites
Next, you can define if the sprite appears above or below the background layer. Currently,
this feature is not working in v0.6.2a and will be available in a future version.
Finally, you can change the sprite’s color offset. The color offset is a value used to shift the
each color index inside of the sprite. This offset allows you to emulate palette swapping by
increasing or decreasing the color values when drawing a sprite to the display. Color offset
can be previewed in the Sprite Tool.
84
Rendering Sprites
It is important to note that sprite draw calls only happen once per frame. If you want a sprite
to remain on the screen, you need to keep calling the DrawSprite() method inside of
Draw() . Likewise, the Display Chip has limitations on how many sprite draw calls it can
render per frame.
85
Rendering Sprites
By default, the maximums allowed sprites at once is 64. After drawing a frame, the sprite
limit is reset and starts back at zero. You can modify this value in the Display Tool.
86
Rendering Sprites
In addition to drawing one sprite at a time, you can also draw multiple sprites to the screen in
a grid to help with rendering larger items. Simply use the apiBridge:DrawSprites() method.
This method accepts an array of sprite IDs along with a width to render it correctly to the
display.
87
Rendering Fonts
Rendering Fonts
Drawing fonts to the display works in a similaraly to sprites. In fact, fonts are simply sprites
who’s character acsii values are mapped over to sprite IDs. When you call DrawFont() and
pass in text, the Font Chip converts each character to a sprite ID and draws it to the display.
You can refernce a font by its name, which is set during the font import step as a game loads
up. Let’s look at a simple font draw call:
apiBridge:DrawFont("Hello World", 0, 0, "large-font", 0)
Here you can see the DrawFont() method accepts a the text to display, an x and y position
as well as the font’s name and finally a color offset value. The following will display this:
Since fonts are comprised of indevidual sprites, each character will count against the total
number of sprites allowed on the screen at one time. Dynamic fonts are very exepensive
because of this and should be used sparingly when possible. Ideally, fonts and text should
be displayed in the tilemap whenever possible.
88
Rendering Fonts
If your game is using the Screen Buffer Chip you can draw fonts directly into the buffer by
taking advantage of the apiBridge:DrawFontToBuffer() method call. Here is an example of
two different fonts displaying their full set of characters in the tilemap.
89
Rendering The Screen Buffer

The Screen Buffer Chip allows you to composite bitmap data at run-time and renders it to
the display. It is similar to tilemap in that it allows you to create an area of pixel data larger
than the current display’s resolution and sample only data you can see. This is done by
modifying the scroll x and y position. When used in conjunction with a tilemap, you can
create a large image in memory and modify it between frame renders.
You will need to make sure you’re game already supports the Screen Buffer Chip in its
data.json by adding the following:
"PixelVision8.Chips.ScreenBufferChip":
{
"backgroundColor":-1,
"viewPortWidth":256,
"viewPortHeight":240
}
Once activated, you can copy over the tilemap to the screen buffer by calling
apiBridge:RebuildScreenBuffer() in your game’s Init() method. Once the screen buffer is
ready, you can copy it to the display by calling apiBridge:CopyScreenBuffer() . You can also
use this API instead of calling the Clear() method since CopyScreenBuffer() completely
replaces the display with the buffer’s pixel data. If there are transparent color references in
the buffer, they are filled in with the background color. Here is an example of a tilemap being
drawn to the display using the screen buffer.
As you can see, the contents of the screen

buffer are wrapping. If you sample a region that is larger than the buffer’s dimensions, it
samples additional pixels to fill the viewport.
90
The screen buffer allows you to render an entire tilemap into memory and helps optimize
rendering larger tilemaps. This is also useful for tilemaps where tiles do not need to change
or need to be constantly updated. The advantage here is that only the data visible to the
screen is copied over to the display when calling CopyScreenBuffer() . Here is an example of
how this works.
You can define the screen buffer’s x , y , width , and height values to control what pixel
data the buffer samples and how it is displayed. Modifying the screen buffer's dimensions
allow you to emulate older 8-bit system’s rendering tricks such as splitting the screen to
render moving objects below a static navbar. You can also move the screen buffer’s scroll
value via the dedicated apiBridge:ScrollTo() method which requires an x and y value.
Changing the scroll value allows you to move the background which is a technique seen in
side scrolling games.
When rendering sprites to the display, by default, they appear above the screen buffer. By
changing the sprite’s layer order, you can change this to render the sprite behind the screen
buffer.
91
Intro To Scripting
Game Scripts
Pixel Vision 8 games can be written in C# or Lua. The Game Creator focus on standardizing
game creation via Lua scripts. These scripts follow the same lifecycle as a Pixel Vision 8
game written in C#. You have hooks for Init() , Update() and Draw() as well as a set of
APIs to draw sprites, fonts, tilemaps and more. Each script is self-contained and included
inside of the Game Creator's project file.
92
Demo Games
Demo Games
The Game Creator ships with several demos to help illustrate how to use Pixel Vision 8's
APIs. These demos can be found in the File Picker tool.
The demos focus on specific aspects of the engine from rendering to handling input and
more. Each demo is open source allowing you to look at source files as well as use the code
in your projects. Here are some of the included demos:
Draw Sprite Demo - Leverages the drawing API to display sprites on the screen.
Font Demo - Illustrates how to render text to the display.
Mouse Demo - Shows off how to capture mouse input and display a cursor on the
screen.
Sprite Stress Test Demo - Highlights the sprite rendering limitation of Pixel Vision 8.
Tilemap Demo - This demo shows off how to load, display and scroll tilemaps.
93
Demo Games
94
Lua Script Sample
Lua Script Sample

The Sprite Stress Test Demo highlights the sprite rendering limitation of Pixel Vision 8.
By default, the DisplayChip can only handle displaying a set number of sprites at the same
time based on the system template you choose. We'll create a loop that attempts to render
more sprites than the system can handle. The outcome is that additional draw calls are
ignored and the engine maintains its optimal performance.
Here is the full Lua script:
95
Lua Script Sample
local delay = 0
local delayTime = 2
local totalSprites = 1000;
function Update(timeDelta)
delay = delay + timeDelta
if(delay > delayTime) then
delay = 0
end
end
function Draw()
apiBridge:Clear()
for i=0,totalSprites,1 do
x = math.random(0,apiBridge.displayWidth)
y = math.random(0,apiBridge.displayHeight)
apiBridge:DrawSprite( i + 12, x, y, false, false, true, 0)
end
end
Let’s walk through the code to see how it uses Pixel Vision 8’s sprite drawing APIs. These
are some fields we'll use for performing the stress test.
local delay = 0
local delayTime = 2
local totalSprites = 1000;
96
Lua Script Sample
The Update() method is part of the game's life cycle. The engine calls Update() on every
frame before the Draw() method. It accepts one argument, timeDelta, which is the difference
in milliseconds since the last frame. We are going to use this timeDelta value to keep track
of the time before changing the background color.
function Update(timeDelta)
We start by adding the time delta to the delay.
delay = delay + timeDelta
Next, we will need to test if the delay value is greater than the delayTime field we set up at
the beginning of our class.
if(delay > delayTime) then
After the appropriate delay, we can change the background color a random value. We'll cap
this between 0 and 63.
We need to reset the delay so we can start tracking it again on the next frame.
delay = 0
Now we just need to close the condition and the function.
end
end
The Draw() method is part of the game's life cycle. It is called after Update() and is where all
of our draw calls should go. We'll be using this to render sprites to the display.
function Draw()
Clearing the display on each frame is important. Since we are not using the
ScreenBufferChip, we can directly clear the DisplayChip by calling the Clear() method.
97
Lua Script Sample
apiBridge:Clear()
This loop will create a random x and y value based on the display's dimension then attempt
to draw a sprite.
for i=0,totalSprites,1 do
x = math.random(0,apiBridge.displayWidth)
y = math.random(0,apiBridge.displayHeight)
apiBridge:DrawSprite( i + 12, x, y, false, false, true, 0)
end
And then we can close the draw function call.

end
Here you can see the lifecycle of the game’s script, as well as a practical example of how to
call Pixel Vision 8’s APIs.
98
Lua API
Lua API
All Lua games have access to a set of APIs that communicate directly with the Pixel Vision 8
engine. These are exposed via the APIBridge. This bridge allows you to access the native
properties and methods of the core framework. While the engine itself contains lots of
separate system working together, only a small subset of these are exposed to the
APIBridge. Additional APIs can be accessed through other bridges which are automatically
loaded by each chip.
Game Lifecycle
The game has several built-in methods you can implement to hook into the engine as it runs.
These are the main methods:
Name Description
This is called when a game is initialized. It is only called once when the
Init()
game is first loaded.
This is called when the game is updated before the draw call. Use this
Update()
method for non-visual updates, such as calculations, input detection, etc.
Draw() This is used for render logic. Place draw calls in this method.
Reset() This is called when a game is reset.
Be sure to check out the source code for each of the demo games to see how all of this
works.
The APIBridge is automatically exposed to game scripts.
Properties
These properties are read only. You can call any of these properties from the APIBridge like
so:
local value = apiBridge:propertyName
Here is a full list of each of the properties available in the APIBridge:
99
Lua API
Name Value Description
displayHeight int The height of the screen in pixels.

displayWidth int The width of the screen in pixels.
Sets the display to wrap sprite pixel data when outside of
displayWrap bool
the screen’s boundaries
inputString string Returns the keyboard input entered this frame.

mousePosition Vector The current mouse position in pixel coordinates.
mouseX int Current x position of the mouse on the screen.
mouseY int Current y position of the mouse on the screen.
paused bool A flag for whether the engine is paused or not.

The horizontal scroll position of the screen buffer. 0 is the
scrollX int
left side of the screen.
The vertical scroll position of the screen buffer. 0 is the top
scrollY int
side of the screen.
spriteHeight int The height of the sprites in pixels.
spriteWidth int The width of the sprites in pixels.
timeDelta float The time difference between the last frame.
Methods
The following methods help expose different aspects of Pixel Vision 8’s chips. You can call
any of these API methods like so:
apiBridge:MethodName(arguments)
Here is a full list of each of the methods available in the APIBridge:
ButtonDown ( int button, int player )
Summary
Determines if a is down on the current frame. Each has a unique ID.
Arguments
100
Lua API
button int Button ID to test.

Id for which player's controller to test. It's set to 0 by default for single
player int
player game.
ButtonReleased ( int button, int player )
Summary
Determines if a was just released on the previous frame. Each has a unique ID.
Arguments
button int Button ID to test.

Id for which player's controller to test. It's set to 0 by default for single
player int
player game.
ChangeBackgroundColor ( int id )
Summary
Changes the background color.
Arguments

id int id to render text with. Uses color ids from the color chip.
Clear ( )
Summary
Clears the display with the current background color.
DrawBufferData ( int[] pixelData, int x, int y, int width, int

height )
101
Lua API
Summary
This draws pixel data directly to the screen buffer. It's the raw drawing API that most buffer
drawing methods use.
Arguments
pixelData int[] An int array of color data that will be converted into pixels.
X position to place pixel data on the screen buffer. 0 is left side of
x int
screen.
Y position to place pixel data on the screen buffer. 0 is the top of
y int
the screen.
width int Width of the pixel data.
height int Height of the pixel data.
DrawFont ( string text, int x, int y, string fontName, int

letterSpacing )
Summary
Draws a font to the display as sprites. This is an expensive draw call since each character is
an individual sprite. Use DrawFontToBuffer() for better performance.
Arguments
text string String that will be rendered to the display.

x int X position where starts on the screen. 0 is left side of screen.
y int Y position where starts on the screen. 0 is top side of screen.

fontName string
letterSpacing int
DrawFontToBuffer ( string text, int column, int row, string

fontName, int letterSpacing )
Summary
102
Lua API
Draws a font to the screen buffer. This allows you to display more without adding extra draw
calls. This may be slow to render a lot of at once so don't call during the draw method.
Arguments

text string String that will be renderer to the screen buffer.
Column position to draw tile to the screen buffer. 0 is the left
column int
of the screen.
Row position to draw tile to the screen buffer. 0 is the top of

row int
the screen.
fontName string
letterSpacing int
DrawPixelData ( int[] pixelData, int x, int y, int width, int

height, bool flipH, bool flipV, bool flipY, int layerOrder, bool
masked )
Summary
This draws pixel data directly to the display. It's the raw drawing API that most display
drawing methods use.
Arguments
103
Lua API
pixelData int[] An int array of color data that will be converted into pixels.
X position to place pixel data on the screen. 0 is left side of
x int
screen.
Y position to place pixel data on the screen. 0 is the top of the
y int
screen.
width int Width of the pixel data.

height int Height of the pixel data.
flipH bool This flips the pixel data horizontally.
flipV bool This flips the pixel data vertically.

Flip the position. This corrects the issue that Y is at the bottom
flipY bool
of the screen.
Defines if the sprite is above or below the background layer. -1
layerOrder int
is below and 0 is above. It's set to 0 by default.
Defines whether the transparent data should be ignored or filled
masked bool
in with the background color.
DrawScreenBuffer ( )
Summary
Draws the screen buffer to the display. The buffer uses its own view port width and height as
well as scroll x and y offsets to calculate what is rendered.
DrawSprite ( int id, int x, int y, bool flipH, bool flipV, bool
aboveBG, int colorOffset )
Summary
Draws a sprite to the display.
Arguments
104
Lua API
id int Index of the sprite inside of the sprite chip.

x int X position to place sprite on the screen. 0 is left side of screen.
Y position to place sprite on the screen. 0 is the top of the
y int
screen.
flipH bool
flipV bool This flips the sprite vertically. Set to false by default.
Defines if the sprite is above or below the background layer. Set
aboveBG bool
to true by default.
This value offsets all the color ID's of the sprite. Use this to
colorOffset int
simulate palette shifting.
DrawSprites ( int[] ids, int x, int y, int width, bool flipH, bool
flipV, bool aboveBG, int colorOffset )
Summary
Draws a group of sprites in a grid. This is useful when trying to draw sprites larger than 8x8.
Each sprite in the array still counts as an individual sprite so it will only render as many
sprites that are remaining during the draw pass.
Arguments

ids int[] Ids of the sprites to draw
x int The upper left corner of where the first sprite should be drawn.
y int The top of where the sprite should be drawn.
width int The width of the larger sprite in columns.
flipH bool
flipV bool
aboveBG bool
colorOffset int
DrawTextBox ( string text, int witdh, int x, int y, string

fontName, int letterSpacing, bool wholeWords )
105
Lua API
Summary
Draws text to the screen with each character being a sprite bound by a specific width.
Arguments

text string
witdh int
x int
y int
fontName string
letterSpacing int
wholeWords bool
DrawTextBoxToBuffer ( string text, int witdh, int column, int

row, string fontName, int letterSpacing, bool wholeWords )
Summary
Draws text to the buffer to a predefined width and word wraps.
Arguments

text string
witdh int
column int
row int
fontName string
letterSpacing int
wholeWords bool
DrawTileToBuffer ( int spriteID, int column, int row, int

colorOffset )
106
Lua API
Summary
Draws a tile to the screen buffer. The buffer represents the rendered data from the tile map.
Drawing to the buffer doesn't change the tile map, it simply alters the cached tile map in
memory.
Arguments
spriteID int Tile to draw to the buffer
Column position to draw tile to the screen buffer. 0 is the left of

column int
the screen.
Row position to draw tile to the screen buffer. 0 is the top of the
row int
screen.
colorOffset int Shift the color IDs by this value
DrawTilesToBuffer ( int[] ids, int column, int row, int

columns, int colorOffset )
Summary
Draws multiple tiles to the screen buffer. The buffer represents the rendered data from the
tile map. Drawing to the buffer doesn't change the tile map, it simply alters the cached tile
map in memory.
Arguments
ids int[] Tile IDs to draw to the buffer
column int The width of the tiles in columns being drawn to the buffer.
Row position to draw tile to the screen buffer. 0 is the top of the
row int
screen.
columns int
colorOffset int Shift the color IDs by this value
GetKey ( int key )
Summary
107
Lua API
Returns true while the user holds down the key identified by the key KeyCode enum
parameter.
Arguments

key int
GetKeyDown ( int key )
Summary
Returns true during the frame the user starts pressing down the key identified by the key
KeyCode enum parameter.
Arguments

key int
GetKeyUp ( int key )
Summary
Returns true during the frame the user releases the key identified by name.
Arguments

key int
GetMouseButton ( int button )
Summary
Determines if the mouse button is down.
Arguments
108
Lua API
button int
GetMouseButtonDown ( int button )
Summary
Arguments
button int
GetMouseButtonUp ( int button )
Summary
Determines if the state of the mouse button.
Arguments

button int
LoadLib( string name )
Summary
Loads an external Lua script and executes it.
Arguments

name string The file should be saved as a .lua file in the Game or Lib folder.
LoadSong ( int id )
Summary
109
Lua API
Loads a song into memory for playback.
Arguments
id int
PauseSong ( )
Summary
Pauses the currently playing song.
PlaySong ( bool loop )
Summary
Plays a song that is loaded in memory. You can chose to have the song loop.
Arguments

loop bool
PlaySound ( int id, int channel )
Summary
Plays a sound from the sound chip.
Arguments
id int Play sound at index in the collection.

Define which channel to play the sound on. Each system has a
channel int
limit of number of sounds it can play at a single time.
ReadData ( string key, string defaultValue )
110
Lua API
Summary
Reads saved data based on the supplied key.
Arguments

key string
defaultValue string
ReadFlagAt ( int column, int row )
Summary
Returns the value of a flag set in the tile map. Used mostly for collision detection.
Arguments

column int Column in the tile map to read from. 0 is the left side of the map.
row int Row in the tile map to read from. 0 is the top side of the map.
RebuildScreenBuffer ( )
Summary
Rebuilds the screen buffer from the tile map. This rendered the entire tile map into the buffer
allowing you to cache the tile map before running the game for optimization.
ReplaceColorID ( int[] pixelData, int oldID, int newID )
Summary
Replaces a single color id in a set of PixelData to a new color
Arguments
111
Lua API
pixelData int[]
oldID int
newID int
ReplaceColorIDs ( int[] pixelData, int[] oldIDs, int[] newIDs )
Summary
Replaces multiples colors in a set of PixelData.
Arguments

pixelData int[]
oldIDs int[]
newIDs int[]
RewindSong ( )
Summary
Rewinds a song to the beginning.
SaveData ( string key, string value )
Summary
Saves data based on a key value pair
Arguments

key string
value string
ScrollTo ( int x, int y )
112
Lua API
Summary
Scrolls the screen buffer to a specific position.
Arguments

x int
y int
SpritesToRawData ( int[] ids, int width )
Summary
This method converts a set of sprites into raw pixel data. This is useful when trying to draw
data to the display but need to modify it before hand.
Arguments
ids int[]
width int
StopSong ( bool autoRewind )
Summary
Stops the current song and auto rewinding it to the beginning.
Arguments

autoRewind bool
ToggleDisplayWrap ( bool value )
Summary
113
Lua API
This enables or disabled the display wrap which allows sprites that go off-screen to be
rendered on the opposite side.
Arguments

value bool
TogglePause ( bool value )
Summary
Arguments

value bool
UpdateTile ( int spriteID, int column, int row, int flag, int
colorOffset )
Summary
Draws a tile into the tile map. Tiles are simply stored in the tile map, you need to render the
tile map to the screen buffer in order to display it.
Arguments
spriteID int Index of the sprite to use from the sprite chip.
column int Column position to draw tile to. 0 is the left of the screen.
row int Row position to draw tile to. 0 is the top of the screen.
flag int
colorOffset int
114
Included Tools
The Included Tools

There are two versions of the Game Creator: Free and Pro. Both versions include the same
basic set of tools for creating new projects, navigating the Workspace's files, saving and
debugging.
The Pro version includes specialized tools for working with colors, sprites, sound effects,
music and more. In addition to the included tools, the Game Creator also offers a set of APIs
and workflows for editing existing tools or building new tools from scratch.
Understanding how these tools work is critical to building Pixel Vision 8 games. While you
can still make games by manually modifying the raw data files included in each game
project, the tools contained in each version of the Game Creator help speed up
115
Included Tools
development. In most cases, these tools offer up a more intuitive way of modifying the
game's contents as well as customizing the underlying system limitations.
116
Navigation Toolbar
The Tool Bar

The Tool Bar represents the strip of icons across the top of the edit mode. Each tool or
action assists with building Pixel Vision 8 games.
Let us start with the left side of the toolbar. These are the tools included with the free version
of Game Creator.
From left to right:
1. New project tool - Creates new games, tools, etc.
2. Save - Archives contents of the Workspace's game folder.
3. File Picker Tool - Opens games, tools, etc.
4. Restart - Reloads the current tool.
5. System Settings Tool - Rename game, ext and global settings.
117
Navigation Toolbar
6. Debug Tool - Displays the log.txt file.
7. Play - Loads the contents of the game directory.
On the opposite side are the core editors. The Pro editor includes these tools.
From left to right:
1. Script Tool - Edits the scripts of a currently loaded game.
2. Display Tool - Edit colors, resolution and draw call limits.
3. Sprite Tool - Preview sprites loaded into memory.
4. Tilemap Tool - Preview tilemap loaded in memory.
5. Sound Tool - Create sound effects.
6. Music Tool - Create song loops.
The toolbar hides and shows icons based on if an action is available or if the tool exists. For
example, when you launch the editor for the first time and no game is present, the toolbar
disables all of the tools on the right-hand side.
If you are using the free version of Game Creator, these tools remain inactive since they not
part of the free version.
118
New Game Tool
New Game Tool

The New Game Tool is designed to simplify creating new projects. It presents a set of 5 built-
in system templates and automatically copies the contents of them over to the Workspace’s
Game folder when you select the New Game button.
Each system template was designed specifically around classic game system’s limitations.
Simply select a system you want to use which updates the system spec preview below:
119
New Game Tool
Each built-in templates is accessible from the File Picker as well.
Whether to chose a system template from the New Game Tool or the File Picker overwrites
the contents of the Game directory with a copy of the selected template. Any changes you
make to the newly created game only affect it and not the source template. The new game's
name is "Untitled_Game" and when you save, it creates a new .pv8 file independent from
the original template.
120
New Game Tool
You can also design your own system template, but only the five built-in ones show up in the
New Project Tool.
121
File Picker Tool
The File Picker Tool

The File Picker Tool allows you to explore the contents of areas inside of the Workspace.
The File Picker is designed to not only show supported file but to help you filter them by
type.
The File Picker Tool is broken down into 3 main sections: currently selected file’s metadata,
file picker area, and action bar.
The first thing we should look at is the currently selected file metadata:
This editor allows you to rename a file, view its extension, and its archived size. Renaming a
file can not be undone, so be careful when changing file names, especially ones that Game
Creator specifically relies on like system templates or tools. If the system detects that a core
tool or file is missing when booting up, it automatically recreates it.
122
File Picker Tool
Next up is the file picker itself which contains three main parts: the picker, the filter, and the
page navigator. Let’s look at the picker first:
The picker can display two columns of file data for a total of 16 files. Each column shows the
extension by icon, a name, and size in kilobytes. Selecting a file updates the editor above
with the currently selected file’s data. Once a file is selected, the editor highlights and can
not be selected.
Below the picker on the left-hand side is a filter tab. The filters allow you to views files by
type:
From left to right:
1. Game Tab - Filter for game (.pv8) files.
2. Tool Tab - Filter for tool (.pvt) files.
3. System Tab - Filter for system template (.pvt) files.
4. Resource Pack Tab - Filter for resource packs (.pva) files.
5. View All Tab - Filter for all supported files.
By changing the filter, the picker displays a new list of files, and the first item in the list is
automatically selected.
123
File Picker Tool
You can navigate through pages of files via the page picker:
This picker gives you options to move to the previous or next page as well as enter a
specific page number you would like to display.
Finally at the bottom of the File Picker Tool is the action bar. This bar is contextual based on
the type of file you have selected. For most files, you have an option to delete or open.
When you select a tool, the picker displays a new "edit" option in the bottom action bar:
124
File Picker Tool
It is important to note the difference between how the editor loads a game and a tool. When
you select a file and press open, the Game Creator looks at its extension and decides where
to load it. Games (.pv8) files are loading into the Workspace’s Game folder. Tools (.pvt) files,
however, are loaded into a temporary folder, and once loaded into memory, the picker
deletes the source files. System templates and Asset Packs are unique. Templates are
copied over and replace the contents of the Game folder. The picker imports the contents of
an Asset Pack into an existing project.
While you can use the File Picker Tool to launch any custom tools you have built, which is
useful when they do not show up in the Toolbar, there are times when you may need to edit
a tool. The contextual Edit button allows you to load a tool into the Game directory and run it
like a game. When you go to save it, the Tool still retains its extension, so you can still save
it as a tool. The option to edit a tool is a powerful feature that also allows you to view or
modify the built-in tools.
The Game Creator was designed to be an open system. You are encouraged to look
through the source code of all of the included projects to see how they work and modify
them as you want. If a particular tool does not suit your needs, go ahead and modify it or
build your own. While the code is open to view, it is not free to re-distribute. Please respect
the license at the top of the tool code.lua file.
If a tool is marked to "not distribute," especially when it is part of Game Creator Pro, it would
be better to make your tool from scratch and borrow what you need.
125
Debug Tool
Debug Tool
The Game Creator includes some basic tools for debugging your game. A lot of this revolves
around the log file maintained by the Game Creator while it is running. You can preview this
log at any time by opening up the Debug Tool.
Here you can read through the log.txt file and see the activity from the engine itself in the
form of errors or Lua print() statements in your game. Here are the three types of messages
you’ll see in the log:
126
Debug Tool
There are two actions you can perform in the Debug Tool, refresh and clear. Both are self-
explanatory. One thing to keep in mind, however, is that Game Creator automatically
destroys the log.txt file when you shut down the application. If you want to save data from
this file, you may need to open it up directly from the Workspace's tmp directory which is
available when the Game Creator is running.
You can open this file in any text editor.
127
Credits
Credits
Pixel Vision 8 was created by Jesse Freeman (@jessefreeman) in collaboration with Pedro
Medeiros (@saint11) for art and Christer Kaitila (@McFunkypants) for music. With additional
coding contributions by Shawn Rakowski (@shwany).
128

Game Creator Instruction Manual v0.6.3

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Game Creator Instruction Manual v0.6.3

Uploaded by

Copyright:

Available Formats

Table

About The Game Creator Documentation

Latest version - v0.6.3 available at http://pixelvision8.com

Jesse Freeman (@jessefreeman)

What is Pixel Vision 8

Game Creator Features

Deprecating editorBridge:LoadLib() which will be removed in v0.7.0a. Use

Fix to the Tilemap Tool to display the correct scroll y value.

Optimized tools to load faster based on new pre-loader logic.

All new boot screen.

Added help messages to all of the tool's UI.

Added support to display line numbers for script errors.

Cleaned up Debugger Tool to now show icons based on event type.

Bug fixes and optimizations.

Cleaned up installer files and updated for v0.6.1a.

Created new Windows installers for free and pro executables.

New controller mapping tool.

Optimized rendered for better performance.

All errors are now displayed in a custom error screen.

Loading and error screens

No sound or music support in this build

Using The Game Creator

Launching the Game Creator

You can change this path to anywhere on your computer.

C:/Users/Jesse Freeman/AppData/LocalLow/Pixel Vision 8/GameCreatorFree/

Yours should be similar with a different user name.

Changing the Workspace Path

Making Pixel Vision 8 Games

Creating A New Game

Here is a breakdown of each property:

W Width The width of the screen’s resolution.

H Height The height of the screen’s resolution.

T Total Total number of colors the system supports.

PS Colors Per Sprite Total colors per sprite.

T Total Sprites The total number of sprites allowed in the memory.

W Width The width (in tiles) of the tile map.

Inside a Game Project

Name Ext. Description

This .png represents collision data in the tile map. It uses a

Type Ext. Description

Working With Archived Games

7. Tile Map Flags

Here is a sample of what a typical data.json file looks like:

Here is an example of the color mapper being turned on and off:

Colors Per Sprite

If we reduce the CPS to 3 you begin losing pixel data:

Sprite Memory Pages

Pages Total Sprites

Working With Large Sprites

The Sprite Builder

Let's take a look at the output:

apiBridge:DrawSprites(playeridle.spriteIDs, 0, 0, playeridle.width, false, false, true

This is what Photoshop exports to the SpriteBuilder folder.

DEC Symbol Description DEC Symbol Description

33 ! Exclamation mark 81 Q Uppercase Q

34 " Double quotes 82 R Uppercase R

38 & Ampersand 86 V Uppercase V

39 ' Single quote 87 W Uppercase W

41 ) Close parenthesis 89 Y Uppercase Y

Period, dot or full

52 4 Four 100 d Lowercase d

58 : Colon 106 j Lowercase j

60 < Less than 108 l Lowercase l

62 > Greater than 110 n Lowercase n