pixelvision8 / pixelvision8

Pixel Vision 8's core philosophy is to teach retro game development with streamlined workflows. PV8 is also a platform that standardizes 8-bit fantasy console limitations built on top of the open-source C# game engine based on MonoGame.

Pixel Vision 8 v2.0 (Archived)

Due to a lack of free time over the past year, I've decided to pause the development of PV8 for the foreseeable future. The code is still open source and free for everyone to fork, modify, and use. I hope to return to this project when I can give it more of my attention and thank everyone for their support over the years.

Pixel Vision 8's core philosophy is to teach retro game development with streamlined workflows. PV8 is also a platform that standardizes 8-bit fantasy console limitations built on top of a fork of MonoGame, called MonoVision. This engine provides a standard set of APIs to create authentic-looking 8-bit games with modern programming languages and workflows. It also allows you to define specific limitations for the resolution, colors, number of sprites on screen, and more.

There are several different ways to build and run Pixel Vision 8, depending on your choice of language, skill level, and goals. You can always get the latest compiled version on itch.io or check out the incremental builds on github.

The platform is incredibly modular and built on a "chip" system that supports swapping out core functionality with new chips. This allows you to customize it to your own needs. While there are tools and a dedicated OS to help make games, nothing stops you from using your external tools and workflows. In fact, the best way to make Pixel Vision 8 games is with the tools and workflow you are most comfortable with already!

Disclaimer

I have been working on Pixel Vision 8 for the past 6+ years and it's still a work in process. I'm doing my best to keep the docs, code base, and examples as up to date as possible, but to help speed up development, consider all the code in this repo experimental. Please join the Discord or subscribe to the new Tutorial Site to learn more about getting started.

Quick Start Guide

I've tried my best to make compiling Pixel Vision 8 from the source as easy as possible. While you can learn more about this in the docs, here is the quickest way to build PV8 from scratch:

Before you get started, you are going to want to install .Net 6, NodeJS, and an IDE like Visual Studio Code.

1. Clone the main repo > git clone https://github.com/PixelVision8/PixelVision8.git
2. Install the NodeJS dependencies > npm install
3. Run the default Gulp action > gulp
4. Launch the .dll manually dotnet Projects/PixelVision8/bin/Debug/net5.0/Pixel\ Vision\ 8.dll

If you want to build Pixel Vision 8 executables, you can use the Gulp action > gulp package. This will create a new Releases/Final/ folder, and inside, you'll zip files for Windows, Mac, and Linux. I call the task via a custom GitHub Action to build and upload the PV8 releases to this repo.

Finally, you can use Visual Studio Code to debug a build by running one of the custom tasks included in the .vscode folder.

Runners

A runner is a wrapper for Pixel Vision 8's core code which allows it to run on different platforms. When you compile PV8 from the default Gulp action, it creates a DesktopRunner that includes all of the "bells and whistles." You may not need that or want to code a PV8 game closer to the metal. You can find the following runners in the Project folder.

1. Pixel Vision 8 Runner - Includes the Lua and Roslyn engines plus a virtual file system, bios, and other hooks to edit games.
2. CSharp Runner - For building pure C# games without the virtual file system, reloading, or boot tools.
3. Roslyn Runner - This is a hybrid CSharp Runner that allows you to reload C# games without recompiling.
4. Lua Runner - For building pure Lua games which support hot reloading but no virtual file system or boot tools.
5. Unity - This is an experimental runner designed to work inside of Unity.

If you are working on a Lua or C# game and would like to distribute it without all of the extra Pixel Vision 8 features, you can look at each of the Runner's .csproj file and replace the path to the Empty Disk with your own game:

<Game>../../Build/Templates/EmptyDisk</Game>

Then when you compile the Runner, the game files will be copied into the game's Content folder and are automatically loaded when the Runner starts. Pay special attention to how the CSharp Runner is structured because you will need to include all of your game's C# code in addition to copying over the game file for it to work.

Games

A lot of people ask where they can find example games. You can check out some of my games like Space Station 8 and Terminal in their repos. I've also created a new Game Repo that people can contribute to by submitting a pull request.

OS

Past versions of Pixel Vision 8 came bundled with an OS and tools installed by default. Suppose you are building PV8 from scratch or using one of the increment releases posted to GitHub. In that case, you can manually boot into the OS by downloading it from the Pixel Vision OS repo and dragging it onto the window. PV8 will remember the last disk it loaded, so you shouldn't have to keep manually booting into the OS unless the system loses a reference to the disk's path or another disk forces the OS disk to eject.

Credits

Pixel Vision 8 was created by Jesse Freeman (@jessefreeman) in collaboration with Christina-Antoinette Neofotistou (@CastPixel) for art, and Christer Kaitila (@McFunkypants) for music.

With additional contributions by the following people:

• Pedro Medeiros
• Shawn Rakowski
• Drake Williams
• Matt Hughson
• Dean Ellis

And special thanks to Jan Rochat, Ethan Shaughnessy, and our other sponsors.

License

Pixel Vision 8 is Licensed under the Microsoft Public License (MS-PL) License. See the LICENSE file in the project root for complete license information.

Pixel Vision 8 is Copyright (c) 2017-2021 Jesse Freeman. All rights reserved.

pixelvision8's Issues

Tilemap color offset should still be loaded reguardless of a json file

Right now the tilemap color offset image isn't loaded if there is a json file. This should always happen since the color offset isn't part of the tile json file.

Need to fix disk count and Back()

When you boot up PV8 without the OS it should only support a single disk. When calling Back() it should eject the disk unless the disk stoped Back(). Also, this feature should be disabled by the standalone runner.

DrawPixel shouldn't need a default draw mode

DrawPixel(0, 0, 1, DrawMode.Sprite) works but DrawPixel(0, 0, 1) does not.

issue during installation & software launch (win10-64bits)

hi,

just got PixelVision 8 and i'm having the following issues :

• During installation of any (draw, tune, make) software :
  

• When launching the software (or any) : nothing happens.

Note : the installation / software is not Signed and not Verified, which is clearly an issue with Windows 10 installs.

I would like to know if there is a log somewhere for analyzing what the problem is and if it's related to my computer or not. (update: it's not as i have tried with other win10 setups).

I will try with linux whenever I got time.

thanks.

Sprite Editor - draw circle

Painted circle has problem with size. Is not painted in radius which is defined by mouse pointer. Max circle size is 6x6/7x7.

Add undo/redo support to color tool

There should be a way to undo and redo color changes in the color tool similar to the SFX and Music Tools.

Remove ColorMap Chip

The color map chip should just be a color chip. Have it leverage the existing code but register it with the engine under a custom name so we can simplify the game engine logic.

Clean up threading

Added threading back in but there are places in the load process where it's not being used. All load processes should run through threading, even if it doesn't show the pre-loader. Need to fix the lockup that happens at the end of the load process as well.

Need to fix color out of range errors

Noticed an issue when the copy pixels draw call is out of range it throws an error:

Press Ctrl + 4 to reload the current game.
  at PixelVision8.Engine.Chips.DisplayChip.CopyDrawRequest (System.Int32[] pixelData, System.Int32 x, System.Int32 y, System.Int32 width, System.Int32 height, System.Boolean flipH, System.Boolean flipV, System.Int32 colorOffset) [0x00099] in <91a832dd36034feeada1515e15dc99a1>:0 

There should be a clamp on the color offset value to keep this from happening.

Use SpriteBlock to simulate Nes sprite 8x16 mode

Need to look into how we can use SpriteBlock to get around the sprite count limitation. Maybe we can define some hardcoded sizes per console that allow for specific block sizes to count as a single sprite.

This could potentially offer a way to clean up the internal sprite size abstraction and hard code sprites to always be 8x8 but allow for defining bigger sprites and removing the penalty. Thinking down the line to better support 16-bit style limitations.

Need to add Ellipse drawing to the Canvas API

Need to replace the circle API with an ellipse.

Add gif capture back in

Need to add the gif capture logic back into the MonoGame runner.

Need a way to export sprites with real colors

If you are drawing sprites with a color map there should be a way to export the colors in their native colors. Also, need to think through how to export sprites in palette mode. This should be part of Pixel Vision 8 Draw.

Print doesn't work

Need to make sure printing to the log works correctly in the desktop runners.

Remove legacy SaveFlags

Remove the following flags which are no longer being used:

TilemapFlags = 2048,
TilemapCache = 4096,
TileColorOffset = 8192,
FlagColors = 16384,

All demos and sample games will need to be moved over to the new tilemap file format.

Need to throw error for font name not found.

Getting an error when passing in the wrong font name as a KeyNotFoundException error. Should capture this and output wrong font error with name being used.

Exporting sprites from image overwrites file if named sprites.png

Need to make sure that the image tool's export feature creates a unique file name.

Remove pages from ColorChip

There is no real need for the notion of pages in the ColorChip and it can now be removed. There should always be 256 colors and it should return a value of how many colors are actually being used.

Bug in Tilemap Cache

Looks like there are some bugs when updating the tilemap cache out of the normal bounds where it doesn't wrap correctly and deletes parts of the tilemap.

Create SDK binary for each release

Need to set up a compiled SDK binary for the next release.

Error ejecting disk

Pixel Vision 8: Play throws an error when ejecting Reaper Boy disk by hitting escape.

image

Also, this is a common error and I need to track down a better way to deal with path issues like this.

Fullscreen boot doesn't set correct resolution

When booting in full screen, the boot tool is not displayed at the correct resolution

Triggering a scale shortcut will actually fix this so maybe it needs to apply the scale after it is in full screen when booting for the first time?

Need to use services better

A lot of classes are hardcoded to the runner. Need to go back through the code and implement the ChipManager's service system better.

can not link to the demo

Hi~
When I tried to click the links in the readme of the project, the link seems to be broken.
They all lead to gitlab links but none of them exist.
Did I miss something ?

Need to expose mask color

ColorChip currently uses a protected transparent color but this should be exposed system wide so it can be changed in the system data file and is used for parsing/exporting.

Create sprite backup

Need to create a backup of the sprite.png file before compressing. This should be an option in the menu. This will just save a copy of the sprite.png file back into the folder letting the create unique filename method append a number to the end of it.

To restore, you'll just need to delete the current sprite.png file in the workspace explorer and rename the backup file to sprites.png.

Color tool sprites can't be optimized

Since the color tool is using a more advanced color-map it corrupts saving out the sprites. Need to look into how this can be fixed using the existing color workflow.

Limit game history to not add existing game when reloading

Looks like the history is adding the current game when reloading and breaks the Back() API.

DrawSpriteBlock - FlipX/Flipy

DrawSpriteBlock paints correct block only in Sprite mode [i.e. 2x2 size], when is used Tile mode is changed only order and graphics is not flipped.

Reported by @AndyGFX

Fix font parsing

Fonts need to be loaded in a 1 bit and not dependant on the system colors. This will allow switching between different color chips.

Last item of Color Picker should be an add icon

Need to use the add icon for the last color value in the picker so it's clear you where to add new colors

Restore load history correctly

Right now the load history is locked at 2 games. If you load a game that loads a 2nd game that loads the 3rd game, the 1st game is reloaded when hitting escape. Need to make sure the back logic is going through the history correctly.

Weird Keyboard layout in the code editor

Using PV8 on a german qwertz-keyboard the keyboard layout is totally messed up, it's a mixture of a german and an english layout:

• characters and digits are mapped to correct keys, even "Y" and "Z" (mysterious - they are switched normally) and "+"
• the special characters ([shift][1..0]) are mapped to english layout, the next two keys do nothing (should print "-","+", "=")
• characters not available: "/", "[", "]","=", quotation marks

So PV8 is currently unusable (at least the code editor).
Here are the different layouts: US / Germany (german wikipedia - they have pictures of both).

Kind regards

Rename realWidth/Height

Need a rename the realWidth and realHeight to better reflect the size of the tilemap in pixels.

Add flip h/v to Canvas DrawSprite method

Need to add support for flip h,v to the Canvas DrawSprite() method so MergePixels() works correctly.

Need to escape linux launch path

There is an issue with the packager that doesn't escape the spaces in the Linux build. Need to address this in the packager kick script.

DrawText is using scroll position

Need to add options to ignore scroll position or manually disable it since it relies on DrawSprites() now.

Saving empty tilemap fails

Creating and saving an empty tilemap from the Tilemap Tool corrupts it in a way where the tool can't reload the file.

To reproduce, create a new project, make an empty tilemap, draw empty sprites, save and reload.

Need to tie spec lock into the system runtime

Need to make sure the spec lock from Pixel Vision OS's Chip Editor is enabled deeper in the system. You shouldn't be able to modify a game's chip properties at runtime. This may require refactoring of the GameChip API a bit.

Need to expose the log calls via the Lua API

There is no way to access the log file internally. Need to expose the log APIs to the Lua Service.

Make Pixel Vision 8's 16 color palette the default colors in the Color Chip

Need to replace black and white with the official 16 color palette for Pixel Vision 8's Color Chip.

LoadService should use AddParser for json parser

Right now the json parser is being manually run and is not part of the full preload process. This could cause problems. Each parser should be part of the load process so the steps can be correctly calculated.

Remove Floats

PV8 doesn't use floats internally with the exception of Update()'s timeDelta. Need to look into making this an int and how badly that will break everything. Also need to make sure we are not using float anywhere else, everything should be int based.

Need API to quickly calculate the palette color offset

Need a new API on the GameChip that calculates the palette color offset based on the palette number, CPS and 128 color offset.

Need to flip the order of arguments in DrawPixels()

Need to make flip H and V come before draw mode.

Remove option to supply DrawMode enum to DrawPixel

Since DrawPixel only works on the TilemapCache layer, the option to supply a DrawMode shouldn't be provided.

Fonts need separate memory space

When importing fonts after sprite, there is a chance the font may corrupt the empty sprites in unoptimized sheets. Here you can see the font characters are filling in empty spaces in sprites that should have transparency but the engine doesn't know about it.

Fonts need their own memory space or should have a dedicated block of sprite memory to avoid this from happing. Maybe there should be a hard limit on the number of fonts you can have like 3 or 1 dedicated page of sprite memory for a total of 256 characters?

GameChip Tile() method should return object

There should be a tile class with all of a tile's properties.

Bounty: Threaded Import/Exporters for Pixel Vision 8 SDK

Bounty Information:
Currently, Pixel Vision 8's SDK contains a set of Parsers. These are using Green Threading to help deal with parsing large chunks of json and png data without locking up the main thread. Currently, this implementation is not ideal and should be moved over to a multi-threaded system to help speed up the time it takes to load and save PV8 games.

Work Needed:
You'll need to take the existing Parsers and convert them into a Background Task or similar threaded task that is supported in .Net 4.5+ and UWP. These parsers are already structured in a way to emulate threading and shouldn't require much additional work to be refactored into something like a BackgroundWorker. The majority of the work will be to make sure that they are thread-safe, that multiple instances of parsers can run concurrently (if more than one game is loading at the same time) and that they are optimized not to block the main thread so the UI can run properly.

Prerequisites:
You'll need to do a little bit of research to figure out the best multi-threading solution that will work for MonoGame. Support for Unity is not required. The goal is to be able to have a single implementation that can be used across MonoGame's Desktop, Mobile, and UWP builds.

Example Code:
The Parsers are located in the Pixel Vision 8 SDK here. Each parser extends the AbstractParser which contains the total number of steps, a way to determine if the parser is completed and a way to call the next step to execute code in the parser.

The LoadService manages creating new parsers and executing them in a single step or in steps via the current green threaded implementation. When the LoadService uses its green thread implementation, each step is called as part of the Runner's Update() function which calls the PreloaderNextStep().

What help can I provide?
I can provide access to the MonoGame runner that currently implements the logic to call the PreloaderNextStep() and passes the loader's percentage to the Lua tools to display the current progress percentage.

Budget/Timeline:

I expect this to take about 1 weekend. 1 day would be spent on reading/research and 1 day would be spent on implementation/testing. I currently have $200 USD allocated for this project.

---

Bounties have the following 3 rules:

1: All source code written is yours to keep. This is NOT a work for hire; you retain full copyright ownership of the code you write. All I am asking is that Pixel Vision 8 gets the right to use/publish that code under the license used by the project. For example, if you release your code under MIT, but Pixel Vision 8 uses MS-PL, the code you contribute goes into the main project under MS-PL with a credit to you as the original creator. The Pixel Vision 8 license may change in the future, so any contributed code adopts the new license where applicable. If you use open-source code with a different license, please make that clear so the correct license and contributor are included. In the end, you can do whatever you want with the code you create after it is accepted. Feel free to continue to work on it, release it under your license, or use it in proprietary projects.

2: You are free to work on the project however you like. If you do a lot of programming on Twitch, for example, you can stream the whole process, and you can publish anything about the project you want, including technical write-ups and example projects. You can also work in whatever environment you want, as long as the final product works on the expected platforms with the expected languages/dependencies. Note, however, that the bounties state a schedule/timeline/budget and those are unlikely to change without a very detailed assessment explaining, for example, why a project could take longer than expected. If you contribute, feel free to put that contribution down on your resume or what have you. If we end up establishing a regular working relationship I am also happy to act as a professional reference for job applications.

3: You are responsible for taxable income made from these bounties. This one's pretty obvious but for those who aren't familiar, this is effectively non-employee income, and you need to pay taxes (depending on where you live). In the United States, for example, this is simply "Other Income" on line 21 of Form 1040. The exception to this rule is if you live in the United States and make more than $600 from my projects, at which point I need a Form W-9 sent to me so I can send you a 1099-MISC next year.

If you have any further questions, feel free to email me.

Gif recorder is not using correct colors in tools

Gif recording in tools is not showing the correct tools. This may be because there are too many colors being fed into the gif recorder. Need to look into how to optimize this since a tool + game will have up to 512 possible colors.

Game Example

Tool Example