This page is in the process of being written. Many details may be inaccurate or missing completely.

Also, XPK Spec 4 is currently being designed. Parts of this specification may be invalid with version 3.

The following content describes the format of a package for XPK Spec 3. Creating and building a package is automated by the scripts in xpk-dev-tools. See the packaging introduction for more information.

The Structure

Xeiso packages are .tar.gz archives with an .xpk extension and a custom gzip header. The gzip header consists of the contents of xeiso.ini (see below) and is stored in the uncompressed FCOMMENT section of the archive. This was done to ensure quick loading of the package name and details by the installer.

The general layout of a Xeiso package is:


packagename.xpk
`-- packagename/
    |-- xeiso.py
    |-- xeiso.ini
    |-- xeiso.run
    |-- package-logo.png
    `-- datafiles/

Replace both instances of packagename with the name or ID of your package.

Basic package requirements:

  1. A xeiso.ini file that contains metadata and other information about your game.
  2. xeiso.pyc must exist. When developing, this may be xeiso.py, but when packaged for distribution this should be compiled to ensure quick loading. (See the xpk-dev-tools package for help on building your game).
  3. You must have a logo image somewhere. No naming requirements; this is specified in xeiso.ini.
  4. A xeiso.run script (in any scriptable language) that will launch your game

Everything else is technically optional, though you might want to at least have an executable if the game is not available on the destination system.

xeiso.ini

Your xeiso.ini file contains basic information needed by Xeiso to load your game into memory. Let’s take a look at xeiso.ini from the demo game:


[demo]
spec: 3
title: Demo Game
description: This is a demo package intended for developers and packages as an example.
logo: demo.png
version: 0.2
fullscreen: 0
hwaccel: 0
joypad: 0
mouse: 0
players: 1
network: 0
parental: 0

Starting from the top: [demo] should be the short name of your game. This should be identical to the folder name you are storing the game in. Keep the brackets intact. spec should always be set to the latest package specification, currently 3. When you upload your package to Xeiso Connect (coming soon!) it will be checked for this.

The contents of this file are inserted into the FCOMMENT header (see above) during the final stage of the build process.

title

description should be self-explanatory, just keep it all on one line.

logo is the name of the logo image for your game, relative to your .ini file.

version is your game’s version number. Increment this to trigger an update if your game is listed on Xeiso Connect.

fullscreen should be 1 if your game runs in fullscreen by default, or 0 if it absolutely has to run in a window.

hwaccel should be 1 if your game uses OpenGL or requires hardware acceleration to run well, 0 otherwise.

joypad and mouse are values that can be set if your game supports or requires either:

  • 0 = not supported
  • 1 = supported
  • 2 = required

players should be set to the amount of players that can play on a single system. Do not count online connectivity.

network: 1 if your game supports online content or play, 0 otherwise.

parental will be used for future parental controls. A minimum age value of 8, 12, 16, or 18 should be set, or 0 if the game is appropriate for all ages1.

xeiso.py (deprecated, will be replaced in spec 4)

This file contains all of the control variables and functions needed to make your game work. It contains everything from launching the game process to custom animated banners. A basic xeiso.py file is as follows:


import xeiso.package

class Package(xeiso.package.Package):
        
    def show_banner(self):
        pass
    
    def hide_banner(self):
        pass
    
    def update(self, dt):
        pass
    
    def draw(self):
        pass

If you find you are not using a particular function of a package, delete the function definition. Xeiso will try to assign a sane default for your game.

A barebones xeiso.py may look like this:


import xeiso.package
class Package(xeiso.package.Package): pass

This “blank” package instructs Xeiso to use its built-in method for generating a game banner. If you would rather not write a custom menu animation, leave this as-is.

Game Banners and Animation

See the demo game package for an example.

Launching your Game

When your game is launched, a number of things occur in the background:

  1. xeiso-launch starts up.
  2. xeiso-ui shuts down.
  3. xeiso-launch loads your game and launches it as a subprocess. (Game is now running.)
  4. When your game exits, xeiso-launch checks to make sure everything was successful.
  5. xeiso-ui is started.
  6. xeiso-launch passes any error messages along to xeiso-ui.

Your game is launched by a script called ‘xeiso.run’. The launch script could be as simple as:


#!/bin/sh

./demo-game
exit

The first line (shebang line) is the interpreter to use; replace this if you would like to use Perl or Python instead to launch your game. If your game is extremely simple, it could actually live entirely inside this script without any additional executables needed. Make sure you mark your script as executable!

Footnotes

1 Currently not used by Xeiso, but expected in a later version.