Table of Contents

Introduction 1.1

Pixel Vision 8 1.2

Change Log 1.3

Quick Start 1.4

Running PV8 1.4.1

Installing Pixel Vision OS 1.4.2

New Projects 1.4.3

Example Lua Game 1.4.4

Exporting Games 1.4.5

Included Tools 1.5

Color Tool 1.5.1

Sprite Tool 1.5.2

Tilemap Tool 1.5.3

SFX Tool 1.5.4

Music Tool 1.5.5

Image Preview Tool 1.5.6

The Log Tool 1.5.7

The Settings Tool 1.5.8

Configuring Controllers 1.5.9

API Cheatsheet 1.6

Credits 1.7

1
Introduction
My name is Jesse Freeman and ever since I turned on my Nintendo 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)

2
What Is Pixel Vision 8
Pixel Vision 8 is the first and only fully customizable 8-bit fantasy console. Don't
just make games, design your own fantasy console specs to match actual
hardware or create something new. It's perfect for game jams, prototyping ideas,
and having fun!

Say Goodbye to the Command Line

Just because you want to make games that look and feel like they were from the
80s doesn't mean you have to use tools like that. Pixel Vision 8 is the first Fantasy
Console to introduce a fully modern OS written entirely from the ground up to run
at 256 x 240. There is no command-line here. Enjoy having a rich user interface
that merges the modern luxuries of today's computers with the nostalgia of 1985.

3
Playing Games
Pixel Vision 8 supports playing games with controllers, the keyboard or a mouse.
Games are self-contained and can even save their progress. You can share PV8
games with your friends that also have a copy of Pixel Vision 8.

4
Insert A Disk
Pixel Vision 8 is like a real game console. Just drop any PV8 disk file onto the
window and watch it load up! Each disk can contain a single game or a collection
of games. You can even have one game load another game inside the same disk
to create more significant experiences.

5
The Pro Tools
While Pixel Vision 8 includes a full set of tools for free, the Pro Tools installer
offers even more enhancements for making games. This upgrade unlocks
additional functionality in the Color, Sound, and Music Tools as well as adding all-
new Chip Editor and Font Tool. The Pro Tools also open up the ability to export
PV8 games as stand-alone executables for Windows, Mac, and Linux.

6
Features
There are two versions of Pixel Vision 8: Free and Pro:

Indie (Free)
The free version of Pixel Vision 8 is a powerful fantasy console with the following
features:

Support for Mac, Windows, and Linux.

Full controller, keyboard and mouse support.

Run in scalable window mode or fullscreen.

Play, Make and Share PV8 games with Pixel Vision OS.

Code games in Lua with an easy to learn set of APIs.

Includes Image Preview, Text, and Settings Tools to get you started.

Use your own tools outside of PV8 to make your games.

Full documentation and tutorials.

Pro (Paid)

7
The paid version Pixel Vision 8 offers additional features to make your own
games inside of PV8:

Everything you get in the Indie plan.

Support for mounting a Workspace folder from your computer to make

sharing files between the two easier.

Includes additional features for the Color, Sprite, Sound, Music, Tilemap, and
Font Tools.

Customize the hardware limitations for each game with the built-in Chip Tool.

Export your games as stand alone executables for Mac, Windows, and Linux.

Pixel Vision 8 is still in development. Currently, it is offered as "early access" and

may contain bugs, unexpectedly crash, or be missing features.

8
Change Log
Pixel Vision 8 and the Pixel Vision OS are constantly being updated based on the
new feature backlog, bugs that need fixing and optimizing the underlying
codebase. Because of this, the goal is to release new versions as often as
possible. If you are new to Pixel Vision 8 or looking to understand what has
changed since the last release, you can find the most recent changes below,
broken down by the version number.

Important Changes
There are some major API changes in this version that may impact reinstalling
Pixel Vision OS on a previous install and how your games run. Here is a list of
major changes and ways to migrate your existing games over to the latest
version.

Upgrading Pixel Vision OS

Issue- If you have a previous version of Pixel Vision OS you’ll get an error after
booting into the Workspace Tool. This has to do with the fact that the
ReadMetaData() API has now been changed to ReadMetadata() . This will impact the
logic that checks if the Explorer Tool should prompt the user to upgrade to the
newer OS.

Fix- Make sure to back up your entire Workspace, then boot up Pixel Vision 8
v0.9.7 while holding down the Shift key to enter safe mode. This will load up the
OS Installer Tool. Check "clean install" then reinstall Pixel Vision OS. You’ll need
to also reinstall your copy of the Pro Tools as well.

Changes to Time Delta

Issue - When you run your games in Pixel Vision 8 v0.9.7, you may notice the
timing is off. The game’s Update() now returns timeDelta as an int instead of a
float which was used in previous versions.

Fix- If you are using the timeDelta in your game’s Update() function, add
timeDelta = timeDelta/1000 to the top of the Update() function which will convert
the value back to a float . This should allow your game to run correctly until you
have time to make the required adjustments to any timeDelta calculations.

API Changes
Here is a complete list of the API changes that are new in v0.9.7:

TotalSprites & TotalColors now default to false. Supplying true will return a
total ignoring any empty sprites or colors.

UpdateTiles API changed from:

9
 UpdateTiles(int column, int row, int columns, int[] ids, int? colorOffset = null,
int? flag = null)

to

UpdateTiles(int[] ids, int? colorOffset = null, int? flag = null)

StopSound() was added to the Lua APIs.

SpriteSize() no longer accepts a width and height parameter since changing

sprite sizes wasn’t supported reviously.
Removed Sprites() API.
Changed DumpMetaData() to ReadAllMetadata() API
Changed ReadMetaData() and WriteMetaData() to ReadMetadata() and
WriteMetadata() respectively.
Added IsChannelPlaying() to Lua API
Remove drawMode parameter from DrawTilemap() . It now automatically
selected the correct drawMode by default.
Changed ConvertCharacterToPixelData() to CharacterToPixelData()

Removed PlayPattern() and PlayPatterns() from the API.

Latest Fixes
This is currently a beta release of Pixel Vision 8. You can now log bugs specific to
Pixel Vision OS here or to the core MonoGame Runner here. There is also a
dedicated Discord Server for community, help, and sharing work. Below are the
issues that have been addressed in this release:

Pixel Vision OS (v2.7.0)

After updating Workspace Explore shows upgrade message again

Color tool should save and restore last selected palette page

Switching to palette mode should fill all colors with default color

Clear palette color doesn't save correctly

Can't preview PVR disks in the Runner folder

Need to remove Revert from the tilemap drop-down menu

Explorer icons show up on shutdown

Arrow keys not working in tilemap sprite picker

Change tilemap picker tool tip to reflect current tool

Songs no longer play back in Music Tool after changing timeDelta to an int

Default template should have locked specs

Remove gitbook link from default project template

Need to disable features of Image Preview Tool

Add x,y to tilemap

10
 Tilemap Tool is not correctly displaying the file extension

Font tool should run game

After editing a font, the background disappears

Need to fix back logic so quitting one tool removes all instances from history

SDK (v1.9.7)
TotalSprites and TotalColors should default to false

Changing UpdateTiles to work with tileIDs, color offsets and flags values

Changing TotalSprites API to default to false

Add StopSound to the Lua API

Remove optional width and height from SpriteSize()

Removed Sprites() API

Change DumpMetaData() api to ReadAllMetadata()

Change ReadMetaData() api to ReadMetadata()

Add IsChannelPlaying to the Lua APIs

Make sure NewPoint and NewRect are part of the C# API

Removed draw mode option from DrawTilemap

Fix template header wrapping

Changed ConvertCharacterToPixelData to CharacterToPixelData

Error tool doesn't display text in Game Runner

Add boot to game runner

Text draw calls are not capped by sprite draw limit

Need to escape linux launch path

11
Quickstart Guide
This quickstart guide is designed to get you up and running with Pixel Vision8. It
covers everything you need to know about launching Pixel Vision 8. Once you've
had a chance to review the information presented here, you'll be ready to start
making your own Pixel Vision 8 games.

12
Running Pixel Vision 8
Pixel Vision 8 works on Mac, PC, and Linux. Simply run the installer or copy it to
where you keep Applications on your computer. Once installed, run the
executable to boot up the Fantasy Console.

By default, Pixel Vision 8 runs in window mode. You can change the scale of Pixel
Vision 8 while it's loading by holding down the 1 - 4 keys or press F to toggle
between fullscreen and windowed mode. Your changes will be saved between
sessions.

13
Pixel Vision 8 will boot up and attempt to run any installed OS. If the OS isn’t
found, you will see the following error.

14
Installing Pixel Vision OS
When you boot up Pixel Vision 8 for the first time, it will ask you to install Pixel
Vision OS.

The installer allows you to select only the parts of the OS you’d like copied over to
the drive. For a fresh install, it’s best to just leave everything selected. When you
are ready, hit the install button and the OS will be copied over to the drive.

15
Once installed, the drive will change icons showing it can be booted and you are
free to eject the disk to reload the OS from the drive.

16
At this point, you should have everything you need to run Pixel Vision OS from the
Workspace drive. The default installation includes a project template you can use
to create new games from scratch. Simply select New Project from the drop-down
menu.

When Pixel Vision OS is correctly installed, you’ll see all of the tools load up on
the boot screen.

17
If a tool you need is missing or wasn’t installed correctly, you can always manually
re-install just that tool by selecting it on the OS installer.

See the reinstalling Pixel Vision OS section for more information on how to do
this.

18
19
New Projects
Pixel Vision OS allows you to create new projects in the Workspace drive or on a
disk that has read/write access on your computer’s file system. You can not
create new projects on the desktop or inside the root of another game’s folder. To
get started, select New Project from the menu and give it a name.

Here is what you’ll see when you create a new PV8 project. This project template
includes all of the core files you need to make a PV8 game.

20
You can run the new game project and it will display some text to let you know
that everything is working and is ready to be modified.

Additional code, json, and font files can be added via the drop-down menu.

21
If a core game file already exists in a game folder, its name will be disabled in the
menu. You can always delete a game file and create a new one from scratch if
you want to start over again. Likewise, creating a new color, sprite, tilemap,
sound, or music file can not be renamed when creating them from scratch.

22
Example Lua Game
Let’s take a look at building a very simple game. We’ll be rebuilding the Sprite
Stress Test Demo which highlights the sprite rendering limitation of Pixel Vision 8.

By default, the Display Chip 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:

23
local delay = 0

local delayTime = 2

local totalSprites = 200

local char = nil

local x = 0

local y = 0

local width = 0

local height = 0

function Init()

local displaySize = Display()

width = displaySize.x

height = displaySize.y

end

function Update(timeDelta)

delay = delay + timeDelta

if(delay > delayTime) then

BackgroundColor(math.random(0, 14))

delay = 0

end

end

function Draw()

Clear()

for i=0,totalSprites,1 do

char = string.char(math.random(33, 126))

x = math.random(0, width)

y = math.random(0, height)

DrawText(char, x, y, DrawMode.Sprite, "large", 15)

end

end

24
Let’s walk through the code to see how it uses Pixel Vision 8’s sprite drawing
APIs. First, create a new project and call it SpriteStressTest.

Next, open up the code.lua file, select all of the code by pressing Ctrl + A , and
then delete it. Now we can start coding from scratch. These are some variables
we'll use for performing the stress test.

local delay = 0

local delayTime = 2

local totalSprites = 200

local char = nil

local x = 0

local y = 0

local width = 0

local height = 0

The Init() method is part of the game's lifecycle and called a game starts. We
are going to use this method to configure background color and get a reference to
the display’s dimensions.

function Init()

It's best to define this outside of the for loop since we only need to set the value
once.

25
 local displaySize = Display()

width = displaySize.x

height = displaySize.y

Now we just need to end the Init() function.

end

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 timeDelta to the delay .

delay = delay + timeDelta

Next, we will need to test if the delay value is greater than the delayTime variable
we set up at the beginning of our class.

if(delay > delayTime) then

After the appropriate delay, we can change the background color to a random
value. We'll cap this between 0 and 14 .

BackgroundColor(math.random(0, 14))

There are 16 colors in Pixel Vision 8’s palette starting at 0 and well save the last
color to use for our sprites later on.

26
We need to reset the delay so we can start tracking it again in 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 a tilemap,
we can directly clear the display by calling the Clear() method.

Clear()

The following loop will create a random x and y value based on the display's
dimension, then we’ll draw a sprite to the screen. It will also pick a random
character by converting an ASCII value to its corresponding string value.

27
 for i=0,totalSprites,1 do

char = string.char(math.random(33, 126))

x = math.random(0, width)

y = math.random(0, height)

DrawText(char, x, y, DrawMode.Sprite, "large", 15)

end

As you can see, we are drawing individual characters to the screen. We’ll be
using the large.font.png file for each sprite. It’s important to note even though the
Font Chip and Sprite Chip store their sprites in separate memory blocks, any
sprite draw call will be limited by the maximum draw calls per frame which we’ll
talk about in a little bit.

Now, the only thing left is to can close the draw function call.

end

At this point, if you run the game by pressing Ctrl + R , it will display all 200
sprites.

The default Pixel Vision 8 game template doesn’t have a cap on the number of
sprites it can draw to the screen. Let’s open up the data.json file and make one
modification.

If you have the Pro Tools installed, you’ll have access to the Chip Editor. Simply
click on the GPU chip, and change the Draws value from 0 to 64 .

28
If you do not have the Pro Tools, you can manually make this change by
modifying the SpriteChip’s maxSpriteCount value. Change the 0 to 64

Now if you rerun the game after saving and closing the data.json file, you’ll see
that PV8 will only draw 64 sprites at any one time.

29
You can continue to play around with this number to see how it affects drawing
sprites to the display. At this point, you should have a basic understanding of a
game’s lifecycle, as well as how Pixel Vision 8’s most common APIs work.

30
Exporting Games
To export a game, navigate to a project in the Workspace Explorer and select
Build from the drop-down menu.

If you do not have the Pro Tools installed, Pixel Vision 8 will create a .pv8 file for
you in a builds folder.

31
Once the PV8 disk has been created, you can navigate to the build folder to see
the disk that was created. You can mount the disk by double-clicking on it. It’s
important to note that you can only have 2 disks mounted at one time. The new
disk will replace the last disk if two are already mounted.

32
Once the disk is mounted, you can open it up, run it, and even modify it just like
any other PV8 disk.

When you are ready to share your game, simply navigate to the Build folder on
your computer. From there, you can upload the .pv8 file to your site to let others
install and play the game on their own copy of PV8.

33
Included Tools
Pixel Vision OS includes built-in tools to help you create PV8 games. These tools
are located in the /Workspace/System/Tools/ folder.

Each tool is registered to edit a specific Pixel Vision 8 file type. For example, if
you open up the Color Tool’s info.json file, you’ll see it is set to edit color files.

34
Pixel Vision OS includes the following built-in tools:

Tool Edit Type File

Color Tool colors colors.png

Image Preview png *.png

Installer Tool installer installer.txt

Music Tool music music.json

Settings Tool settings n/a

SFX Tool sounds sounds.json

Sprite Tool sprites sprites.png

Text Editor Tool txt, json, info, lua *.txt, *.json, info.json, *.lua

Tilemap Tool tilemap, tiles tilemap.json, tilemap.png

Workspace Tool workspace n/a

In addition to the built-in tools, you can also build your own. If a PV8 game is
located in a /System/Tools/ folder, Pixel Vision OS will attempt to register it with
the file type it is associated with in the info.json file. That means you can create or
modify replacements for any of the built-in tools for your own specific needs. You
can even have System folders on disks and they will load on top of the
Workspace drive if you want to run your tools from disks and not install them over
the built-in ones.

35
Color Tool
Pixel Vision OS has a built-in Color Tool to make previewing and editing system
colors easier. You can use the Color Tool to also create individual palettes for
swapping at run-time.

Keyboard Shortcuts
The Color Tool has the following keyboard shortcuts based on what actions are
available.

36
Name Shortcut Description

Save Ctrl + S Save the changes to the color.png file.

Add a new color to the right of the currently

Add Ctrl + A
selected color.

Edit Ctrl + E Edit the currently selected color.

Clear the currently selected palette color. This will

Clear Ctrl + B
make the color transparent.

Delete Ctrl + D Delete the currently selected color.

Undo Ctrl + Z Undo the last color change.

Redo Ctrl + X Redo the last color change.

Copy Ctrl + C Copy the currently selected color.

Paste Ctrl + V Paste the currently selected color into a palette.

Quit Ctrl + Q Quit the current tool.

37
Sprite Tool
The Sprite Editor Tool allows you to preview and edit sprites in memory. This tool
is critical to see all of the sprites that are imported into the game and verifying that
they are displayed correctly. Let's take a look at the Sprite Editor Tool's default
layout.

The tool is broken down into 3 parts: the sprite editor, the sprite picker, and the
color picker. Let’s get started by talking about the picker. This tool is rather
straightforward. Simply select a sprite you would like to edit and it will load up on
the canvas. Use the tools to modify it, and once saved, the sprites.png file will be
updated with the changes.

Keyboard Shortcuts
The Sprite Tool has the following keyboard shortcuts based on what actions are
available.

38
Name Shortcut Description

Clear all of the pixel data in the currently selected

Clear Ctrl + D
sprite.

Save Ctrl + S Save the changes to the sprites.png file.

Undo Ctrl + Z Undo the last sprite pixel data change.

Redo Ctrl + Y Redo the last sprite pixel data change.

Copy Ctrl + C Copy the currently selected sprite.

Paste the previously copied sprite data over to the

Paste Ctrl + V
currently selected sprite.

Quit Ctrl + Q Quit the current tool.

39
Tilemap Tool
The Pixel Vision 8 has a built-in tilemap editor which is designed to help you build
levels, splash screens, and backgrounds for your games.

The tilemap editor is broken up into 4 main parts: the sprite picker, the color/flag
picker, the tools, and the tilemap editor. In addition to the tilemap editor, you can
use the Tilemap Tool to create collision flags by switching over to the flag picker.

Keyboard Shortcuts
The Tilemap Tool has the following keyboard shortcuts based on what actions are
available.

40
Name Shortcut Description

Save Ctrl + S Save the changes to the tilemap.json file.

Clear Ctrl + D Clear the currently selected tile or flag.

Undo Ctrl + Z Undo the last tile or flag change.

Redo Ctrl + Y Redo the tile or flag data change.

Copy Ctrl + C Copy the currently selected tile or flag.

Paste the previously copied tile or flag over to the

Paste Ctrl + V
currently selected tile location.

BG Toggle between showing and hiding the

Ctrl + B
Color background color.

Flip H Ctrl + H Flip the currently selected tile horizontally.

Flip V Ctrl + G Flip the currently selected tile vertically.

Quit Ctrl + Q Quit the current tool.

41
SFX Tool
The SFX Tool allows you to create sound effects for your game and instruments
to be used in the Music Tool. At a high level, the SFX Tool is optimized to make
sound effects for your games as easy as possible by offering templates to
streamline the creation of sound assets. Here is what the tool looks like:

The tool is broken up into 3 main areas: sound info, presets, and settings.

Keyboard Shortcuts
The SFX Tool has the following keyboard shortcuts based on what actions are
available.

42
Name Shortcut Description

Creates a new sound effect over the currently

New Ctrl + N
loaded sound.

Save Ctrl + S Save the changes to the sounds.json file.

Export
Ctrl + E Exports the current sound effect as a .wav file.
SFX

Reverts the current song back to its previously

Revert Ctrl + R
loaded state.

Undo Ctrl + Z Undo the last sound property change.

Redo Ctrl + Y Redo the last sound property change.

Copy Ctrl + C Copy the currently selected sound.

Paste the previously copied sound over to the

Paste Ctrl + V
currently selected sound.

Randomly mutates the current sound effects

Mutate Ctrl + M
properties to produce a new sound effect.

Quit Ctrl + Q Quit the current tool.

43
Music Tool
The Music Tool allows you to create music from scratch, edit existing songs, and
can also generate random music to help get you started. This is what you are
presented with when loading up a music.json file.

The Music Tool is divided into 4 different zones: song playback, song editor, the
tracker, and note input.

Keyboard Shortcuts
The Music Tool has the following keyboard shortcuts based on what actions are
available.

44
Name Shortcut Description

Save Ctrl + S Save the changes to the music.json file.

Undo
Ctrl + Z Undo the last note change.
Note

Redo
Ctrl + Y Redo the last note change.
Note

Clear
Ctrl + D Clear the currently selected note.
Note

Copy
Ctrl + C Copy the currently selected sound.
Note

Paste Paste the previously copied sound over to the

Ctrl + V
Note currently selected sound.

Export
Ctrl + E Export the current song to a .wav file.
Song

Quit Ctrl + Q Quit the current tool.

45
Image Preview Tool
Pixel Vision OS has a built-in image viewer. You can use it to open any .png file
that is not associated with an editor. You can tell a file will be opened by the
Image Preview Tool if it has the generic PNG icon.

After double-clicking on a file ending in .png , the Image Preview Tool will display
it. If the image is larger than the preview window, you’ll be able to scroll
horizontally or vertically via the scroll bars on the right and bottom of the tool.

46
It’s important to note that special image files such as the colors.png , sprite.png

and tilemap.png file will be opened with their respective editors if they are inside
of a game project folder.

47
Log Tool
Pixel Vision OS includes a basic tool for viewing Pixel Vision 8’s log file. This file
is maintained and updated while Pixel Vision 8 is running.

You can preview this log at any time by opening up the Debug Tool from the
Workspace Explorer’s drop-down menu.

48
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.

49
One thing to keep in mind, however, is that Pixel Vision 8 automatically destroys
the log.txt file when you shut down Pixel Vision OS. You can access the raw
log.txt file at any time from Pixel Vision 8’s Tmp directory on your computer.

The log.txt file is located in one of the following locations based on the OS you
are running Pixel Vision 8 on.

Version Path

Windows C:\Users\UserName\AppData\Local\PixelVision8\Tmp\Trash\

MacOS /Users/UserName/.local/share/PixelVision8/Tmp/Trash/

Linux /Users/UserName/.local/share/PixelVision8/Tmp/Trash/

If you would like to view the log while running Pixel Vision 8, you can open it from
the termnial window or use a text editor that automatically refreshes files after
external changes are detected.

50
Settings Tool
The System Setting Tool allows you to configure the global settings of Pixel Vision
OS in one place. The Settings Tool is available from the Workspace Explorer’s
drop-down menu.

The first panel of the settings tool allows you to modify the system volume. This
will not only affect the currently loaded game, but all sounds played by Pixel
Vision 8.

You can also mute all sounds if you prefer to work in silence. Pixel Vision 8 saves
the mute and volume values in the user-bios.json .

The next setting panel controls Pixel Vision 8’s resolution. Changes made to
these settings are applied immediately. The first option is changing the scale of
Pixel Vision 8’s window.

51
When in windowed mode, Pixel Vision 8’s native resolution is 512 x 480. Games
are scaled up to fit inside of that resolution. Since Pixel Vision OS’s resolution is
set to 256 x 240, it will be scaled x2 to fit inside of the window. This allows Pixel
Vision 8 to support game resolution of up to 512 x 480.

There are 4 scale options to chose if you want to change the size of Pixel Vision 8
in window mode. Scale mode 1 sets the resolution to 512 x 480. Increasing the
scale to 2 changes the window size to 1024 x 960. You can not resize the window
manually. This scale system ensures that games always look pixel-perfect at the
correct resolution.

Be careful not to change the scale to something larger than your monitor can
support or you’ll need to restart Pixel Vision 8 and hold down the 1 key while the
boot animation is playing to reset the scale back to its default value.

One thing to note, when creating games at resolutions that are not 256 x 240, is
that black bars are displayed based on the game's suggested aspect ratio.

You can remove the black bars in window mode by checking the crop setting.

52
When crop is on, Pixel Vision 8 will scale the game up to fit in the vertical height
of 480 pixels. From there, the window chrome is resized horizontally to fit perfectly
around the game at its newly upscaled resolution.

Pixel Vision 8 will always prioritize maintaining perfectly square pixels when
upscaling games of any resolution. You may find some resolutions work better
than others so keep these settings in mind when designing your game’s
resolution.

The last option is fullscreen, which allows Pixel Vision 8 to completely take over
the entire screen. When going into fullscreen mode, the Game Creator
automatically adjusts the scale mode based on your monitor’s maximum vertical
resolution. Since most monitors are 16:9, there will always be black bars on the
sides of the game. You can use the full-screen option to stretch the image and
remove the bars.

53
As you can see, this will stretch the image horizontally and Pixel Vision 8 will not
be able to maintain perfectly square pixels.

If you run into an issue with fullscreen or scale mode, you can manually change
the values in the user’s bios file. Simply search for FullScreen Or Scale :

If you change these values and restart Pixel Vision 8, it should adjust the display
accordingly. Just be sure to only change user bios settings when Pixel Vision 8 is
shut down or your changes may be overwritten when quitting.

The last resolution option is CRT mode. Checking this will apply a CRT shader
filter to the entire screen.

When this mode is activated, you will see scanlines and the edges of the display
will be slightly warped as if PV8 was being viewed on a CRT monitor.

54
You may need to restart Pixel Vision 8 in order to see the CRT filter correctly the
first time you apply it. Also in CRT mode, you will have access to adjusting the
brightness and sharpness of the CRT monitor.

It’s important to note that the CRT filter is not applied to any screenshots or
recordings done while a game is running. This effect can only be seen on the
Pixel Vision 8 window itself.

Finally, the last panel allows you to change the shortcut keys for taking
screenshots and animated gifs in Pixel Vision 8.

You can change the shortcuts to any number from 0-9 on your keyboard as long
as it does not conflict with another keyboard shortcut.

55
Configuring Controllers
Pixel Vision OS supports configuring game controllers in addition to mapping the
keyboard to buttons. You can access this from the Settings Tool in the drop-down
menu. As of now, controller support and remapping keys are still experimental.

You can toggle between the controller and keyboard mapping for each player.

56
Pressing a button on the keyboard or controller will display on the screen to verify
that it is capturing the input correctly.

57
GameChip API
All Pixel Vision 8 games have access to a set of common set of APIs. These are
exposed via the GameChip . These APIs allow you to access the underlying system
chips. Below is a list of the most common APIs.

Color
These APIs manage system colors and the background color used to clear the
display.

BackgroundColor ( id )

The background color is used to fill the screen when clearing the display. You can
use this method to read or update the background color at runtime. When calling
BackgroundColor() without an argument, it returns the current background color as
an int. You can pass in an optional int to update the background color by calling
BackgroundColor(0), where 0 is any valid system color ID.

Color ( id, value )

The Color() API allows you to read and update color values in the ColorChip .
This API has two modes that require a color ID to work. By calling the method
with just an ID, like Color(0) , it returns a HEX string for that color. If you supply
an additional HEX string value, like Color(0, "#FFFF00") , you can change the color
with the given ID.

Drawing
These APIs are in charge of copying pixel data to the display.

DrawRect ( x, y, width, height, color, drawMode )

The DrawRect() API allows you to display a rectangle with a fill color on the
screen. Since this API uses DrawPixels() , rectangles can be drawn to the tilemap
cache or sprite layers.

DrawSprite ( id, x, y, flipH, flipV, drawMode, colorOffset )

The DrawSprite() API allows you to draw a single sprite to the display. Sprites
represent individual collections of 8 x 8 blocks of pixel data. The display also has
a limitation on how many sprites that can be on the screen at the same time. Each
time you call DrawSprite() , the sprite counts against the total amount the display
can render.

DrawSpriteBlock ( id, x, y, width, height, flipH, flipV, drawMode, colorOffset,

onScreen, useScrollPos, bounds )

DrawSpriteBlock() is similar to DrawSprites except you define the first sprite

(upper left corner) and the width x height (in sprites) to sample from sprite ram.

58
DrawSprites ( ids, x, y, width, flipH, flipV, drawMode, colorOffset, onScreen,
useScrollPos, bounds )

The DrawSprites() API makes it easier to draw a group of sprites to the display.
Unlike the DrawSpriteBlock() API, you define the exact sprites you want to be
drawn. While there is no limit on the size of the sprite group which can be
rendered, it is important to note that each ID in the array still counts as an
individual sprite.

DrawText ( text, x, y, drawMode, font, colorOffset, spacing )

The DrawText() API allows you to render text to the display. Files ending with the
.font.png extension are loaded by the FontChip and converted into character
sprites. The FontChip stores these characters separately from SpriteChip ’s own
sprites.

File IO
These APIs allow you to read and write save data to handle persistent game data.

ReadSaveData ( key, defaultValue )

The ReadSaveData() API allows you to read saved data by supplying a key. If no
matching key exists, " undefined " is returned.

WriteSaveData ( key, value )

The WriteSaveData() API allows you to write saved data by supplying a key and
value. Once saved, this data persists even after restarting a game.

Input
These APIs handle input from the system’s controllers, keyboard, and mouse.

Button ( Buttons button, InputState state, int controllerID )

The main form of input for Pixel Vision 8 is the controller's buttons. You can get
the current state of any button by calling the Button() method and supplying a
button ID. There are optional parameters for specifying an InputState and the
controller ID.

Key ( key, state )

While the main forms of input for Pixel Vision 8 are the controllers, you can test
for keyboard input by calling the Key() API. When this API is called, it returns the
current state of that specific key.

MouseButton ( int button, InputState state )

Pixel Vision 8 supports mouse input. You can get the current state of the mouse's
left ( 0 ) and right ( 1 ) buttons by calling MouseButton() API. In addition to
supplying a button ID, you can also provide an option InputState .

MousePosition ( )

59
The MousePosition() API returns a Point for the mouse cursor's X and Y

position. The mouse's 0 , 0 position is in the upper left-hand corner of the

display and when the mouse is off-screen it will return -1 . This value is read-
only.

Lifecycle
The following functions are automatically called when your game is running.

Init()

This is called when a game first loads up.

Draw()

Draw() is called once per frame after the Update() has been completed. This is
where all of your game's draw calls should take place such as clearing the
display, drawing sprites, and pushing raw pixel data into the display.

Update( timeDelta )

Update() is called once per frame at the beginning of the game loop. This is
where you should put all non-visual game logic such as character position
calculations, detecting input and performing updates to your animation system.
The timeDelta is provided on each frame so you can calculate the difference in
milliseconds since the last render took place.

Music
These APIs allow you to manage music in your game.

PauseSong ( )

The PauseSong() API toggles the current playback state of the sequencer. If the
song is playing, it will pause. If the song is paused, it will play.

PlaySong ( id, loop, startAt )

The PlaySong() API allows you to activate the MusicChip ’s tracker to playback
any of the songs stored in memory. A song is simply a collection of patterns. You
can supply an optional parameter called startAt to tell the MusicChip which
pattern to start the song at.

RewindSong ( position, patternID)

The RewindSong() API allows you rewind the currently playing song to a specific
position and pattern ID. Calling this API without any arguments will simply rewind
the song to the beginning of the first pattern.

StopSong ( )

The StopSong() API will stop the currently playing song.

60
Rendering
These APIs are in charge of managing what renders to the display.

Display ( visible )

The Display() method allows you to get the resolution of the display at run time.
By default, this will return the visible screen area based on the overscan value set
on the DisplayChip .

RedrawDisplay ( )

The RedrawAPI() allows you to execute both the Clear() and DrawTilemap() APIs
in a single call. This is a simple helper function to make redrawing the display
easier. If you need to supply additional arguments to either the Clear() or
DrawTilemap( ) APIs, then you’ll need to call each one independently without using
RedrawDisplay() .

ScrollPosition ( x, y )

You can scroll the tilemap by calling the ScrollPosition() API and supplying a
new scroll X and Y position. By default, calling ScrollPosition() with no
arguments returns a Point with the current scroll X and Y values. If you supply
an X and Y value, it updates the tilemap's scroll position the next time you call
the DrawTilemap() API.

Sounds
These APIs allow you to play sound effects on specific audio channels.

PlaySound ( id, channel )

The PlaySound() API allows playing a single sound effect on a specific channel.
The SoundChip has a limited number of active channels, so playing a sound effect
on a channel where a sound is already playing will override it.

Sound ( int id, string data )

The Sound() API allows you to read raw sound data from the SoundChip . You
need to provide a sound effect ID. If you supply the optional data argument, which
is a comma-delimited string of sound effect property values, you’ll be able to
update the sound effect.

StopSound ( channel )

Use StopSound() to stop any sound playing on a specific channel.

Sprites
These APIs allow you to manage sprite pixel data and get the total amount of
sprites in memory.

Sprite ( id, data )

61
The Sprite() API allows you to read and write pixel data directly to the
SpriteChip ’s memory. Sprite pixel data is simply an array of color IDs. When
calling the Sprite() with only an ID argument, you will get the sprite's pixel data.
If you supply data, it will overwrite the sprite.

TotalSprites ( bool ignoreEmpty )

The TotalSprites() API returns the total number of sprites in the SpriteChip . By
supplying true for the ignoreEmpty parameter, it will only return sprites that
contain pixel data.

Tilemap
These APIs allow you work with tilemap data.

Flag ( column, row, value )

The Flag() API allows you to quickly access just the flag value of a tile. This is
useful when trying to calculate collision on the tilemap. By default, you can call
this method with just a column and row position to return the flag value at that tile.
If you supply a new value, it will be overridden on the tile.

RebuildTilemap ( )

The RebuildTilemap() API forces the tilemap to redraw the tilemap cache layer.
Use this to clear any pixel data drawn on top of tiles in the tilemap cache layer.

Tile ( column, row, spriteID, colorOffset, flag, flipH, flipV )

The Tile() API allows you to get the current sprite, color offset and flag values
associated with a given tile ID. You can optionally supply your own values if you
want to update the tile.

TilemapSize ( width, height, clear )

The TilemapSize() API returns a Point representing the size of the tilemap in
columns ( X ) and rows ( Y ). To find the size in pixels, you will need to multiply
the returned Point ’s X and Y values by the sprite size's X and Y . This
method also allows you to resize the tilemap by passing in an optional new Width

and Height .

UpdateTiles ( ids, column, row, width, colorOffset, flag )

The UpdateTiles() API allows you to update the color offset and flag values of
multiple tiles at once. Simply supply an array of tile IDs and the new tile’s color
offset and a flag value. This helper method uses the Tile() API under the hood
to update each tile, so any changes to a tile’s color offset will automatically force it
to be redrawn to the tilemap cache layer.

62
Credits
Pixel Vision 8 was created by Jesse Freeman (@jessefreeman) and Christina
Antoinette Neofotistou (@CastPixel) in collaboration with Pedro Medeiros
(@saint11), Christer Kaitila (@McFunkypants), and Shawn Rakowski (@Shwany).

63