Resource Embedding in PIGO8

Quick Start Guide

To create a portable PIGO8 game that works anywhere:

Add this line at the top of your main.go file:

//go:generate go run github.com/drpaneas/pigo8/cmd/embedgen -dir .

Run these commands before distributing your game:
```
go generate
go build
```

That's it! Your game binary will now include all necessary resources and work correctly even when moved to a different directory.

What This Does

PIGO8 uses the following resource files for games:

map.json - Contains the game map data
spritesheet.json - Contains sprite definitions and pixel data
palette.hex - Contains custom color palette definitions

The go generate command automatically creates an embed.go file that embeds these resources into your binary, making your game fully portable.

How Resource Loading Works

PIGO8 uses a smart resource loading system with the following priority order:

Files in the current directory (highest priority)
Common subdirectories: assets/, resources/, data/, static/
Embedded resources registered via RegisterEmbeddedResources
Default embedded resources in the PIGO8 library (lowest priority)

This approach gives you the best of both worlds:

During development: Edit local files for quick iteration
For distribution: Embed resources for portability

Detailed Usage Guide

Automatic Embedding with go:generate (Recommended)

PIGO8 provides a tool that automatically generates the necessary embedding code for your game. This is the recommended approach for distributing your game.

Add this line at the top of your main.go file:

//go:generate go run github.com/drpaneas/pigo8/cmd/embedgen -dir .

Run the generate command to create the embed.go file:
```
go generate
```
Build your game normally:
```
go build
```

The generated embed.go file will embed your map.json, spritesheet.json, and palette.hex files into the binary. Your game will now work correctly even when moved to a different directory.

Manual Embedding (Alternative)

If you prefer to manually control the embedding process, you can create an embed.go file in your project:

package main

import (
 "embed"
 
 p8 "github.com/drpaneas/pigo8"
)

// Embed the game-specific resources
//
//go:embed map.json spritesheet.json palette.hex
var resources embed.FS

func init() {
 // Register the embedded resources with PIGO8
 // Audio will be automatically initialized if audio files are present
 p8.RegisterEmbeddedResources(resources, "spritesheet.json", "map.json", "palette.hex")
}

Adjust the go:embed directive to include only the files you have. For example, if you only have a palette.hex file, your embed.go would look like:

package main

import (
 "embed"
 
 p8 "github.com/drpaneas/pigo8"
)

// Embed the game-specific resources
//
//go:embed palette.hex
var resources embed.FS

func init() {
 // Register the embedded resources with PIGO8
 // Audio will be automatically initialized if audio files are present
 p8.RegisterEmbeddedResources(resources, "", "", "palette.hex")
}

Custom Color Palettes with palette.hex

PIGO8 now supports custom color palettes through a palette.hex file. This allows you to use color palettes from sites like Lospec in your games.

Creating a palette.hex File

Visit Lospec Palette List and find a palette you like
Download the palette in HEX format
Save it as palette.hex in your game directory

Each line in the palette.hex file should contain a single hex color code, for example:

c60021
e70000
e76121
e7a263
e7c384

How Palette Loading Works

When a palette.hex file is loaded:

The first color (index 0) is automatically set to be fully transparent (rgba(0, 0, 0, 0))
All colors from the palette.hex file are shifted up by one index
The palette can be used like any other PIGO8 palette

Example Usage

See the examples/palette_hex directory for a complete example of loading and using a custom palette.

Resource Loading Priority

PIGO8 uses the following priority order when looking for resources:

Files in the current directory (highest priority)
Custom embedded resources registered via RegisterEmbeddedResources
Default embedded resources in the PIGO8 library (lowest priority)

This allows you to:

Develop with local files for quick iteration
Distribute with embedded resources for portability
Always have fallback resources from the library

PIGO8 Documentation