Projects & Assets

Pyxen uses a simple file-based project model: your projects are files on your device. An account is optional, and nothing needs one.

The .pyxen format

A Pyxen project is a .pyxen file. It’s a ZIP archive containing your code, images, and sounds. You can:

Because it’s a standard ZIP, you could even unzip it on a computer to inspect the contents.

A project remembers which Pyxen saved it. A project made with a newer Pyxen still opens and runs; the first time you open it, Pyxen says once that what the newer version added may not show or work until you update. Nothing is refused.

Where your projects are

Pyxen keeps the projects you save in its folder: iCloud Drive › Pyxen when iCloud Drive is on for Pyxen, otherwise Pyxen’s own folder on the device (On My Mac › Pyxen on the Mac, On My iPad › Pyxen in the Files app on the iPad). Settings › General › Projects says which, and Show in Finder (on the iPad, Show in Files) opens it.

On Windows, Pyxen keeps them in Documents › Pyxen: Settings › General › Projects says so, and Show in File Explorer opens it.

For the project you have open, click or tap its name in the title bar and choose Show in Finder (Show in Files on the iPad), or choose File › Show in Finder (⌥⌘R). On the home, it’s in a project’s menu. The Files app can’t select a file, so on the iPad it opens the folder the project is in. A project you haven’t saved yet isn’t in any folder: its menu offers Save… instead.

On Windows, it is Show in File Explorer, in the same places, or File › Show in File Explorer (Ctrl+Alt+R).

A project you saved or opened somewhere else stays where it is: Pyxen lists it in Continue and never moves it. While you try Pyxen, the projects in its folder are the ones that count.

Folder projects

On the Mac and on Windows, a project can also be a folder of plain files instead of a single .pyxen: the same files a .pyxen holds, side by side, so a text editor, git or an AI app can work on them directly.

Pyxen 26.6 and earlier, and Pyxen on iPad, open .pyxen files only: convert a folder project to a .pyxen file for them or to share it.

Adding assets

Your project can contain:

A project’s README.md, and its translations such as README.fr.md, are one Read Me row at the top of Files, above Scripts. It opens the page in your language. Its menu has the other languages (Open in Another Language) and Edit as Text, which opens the file itself.

Add assets with File › Import Images or Sounds…, or make one with File › New Asset… (the + in Files). Once added, you reference them by name in your code:

Sprite("hero")       # references an image named "hero"
Sound("jump")        # references a sound named "jump"
Music("overworld")   # references a music track named "overworld"

A new tile map

In File › New Asset…, Tilemap asks which tiles the map is painted with. It shows the project’s images, each with how many tiles it makes, then the images of the asset packs the project uses, under each pack’s name, and last Pyxen’s Tiles: ground, walls, floors, a door, a target, hills, clouds, bushes and a crate, 40 tiles of 16 pixels in the project’s palette.

A new map starts with the tiles another map of the project uses, else an image whose name says “tiles”, else Pyxen’s Tiles. Tileset names the choice, and the line under it says what Create does:

Cell Size follows the choice, and you can still change it. The map’s Map Settings › Tileset links it to another image later.

Pyxen’s Tiles are drawn in the project’s art style. Project Settings › Art › Change Style… draws tiles.png again while you haven’t changed it, and leaves it as it is once you have.

Asset packs

Pyxen includes asset packs — collections of images, sounds, and tiles that you can use in your projects. Asset packs use the .pyxenpack format (also a ZIP archive).

A few packs come with the app. The others are downloaded when you choose them: their card says Download and the pack’s size, and a project that uses a pack this device doesn’t have yet offers the download in its Files list. If the download can’t happen (you’re offline, for instance), Pyxen says so and your project stays as it was. New packs can appear without an update to Pyxen: it checks the list of packs when it starts and when you open Asset Packs, and offline it shows the list it saw last.

Each pack’s page says who made it and how you may use it. Most packs are public domain (CC0): use them freely, in exported games too. A pack marked Credit required asks your game to name its maker. When you export, Pyxen writes the credits of every pack the game uses into licenses.txt and CREDITS.txt; the page’s Copy the Credit gives you the line for anywhere else.

A pack’s files are shared by every project that uses it, so they open read-only, with a bar that says whose they are. To change one, choose Edit a Copy in that bar or in the file’s menu in Files (drawing on it opens the same sheet): the file, or the frame you picked, becomes your project’s own, and the code that names it uses the copy, in one step that Undo takes back. The copy keeps its credit. Project Settings › Credits lists everything in your game that someone else made, says Changed once you change a copy, and keeps your own thanks; Preview CREDITS.txt shows what an export writes.

Mechanics

Mechanics are ready-made game pieces written in Pyxen Script: platformer movement, health and damage, pickups, a score, a camera that follows the hero, and more. Open them from Project Settings › Mechanics, from Mechanics… in the ⋯ menu, or with the + of the Mechanics group in Files.

There, they are sorted by what they do:

Level from Text builds a level from rows of letters in your code, or from a map painted in the Tilemap editor, where it finds each thing by its name.

Each mechanic has a page. Its test scene runs there as a demo: click it to play with the keys, and press Escape to give the keys back. Its settings’ sliders change the demo as you drag, and save nothing. How to Use shows the lines to write, Code the whole file, and What it offers its functions, as completion shows them.

Add to Project copies the mechanic’s file into your project, its comments in your language, with any mechanic it needs (the button names them). It is one step: Undo takes all of it back. The file is yours to read and change. Files lists it under Mechanics with its version, and says Changed once you edit it. Remove… asks first, and names the mechanics that need it.

A mechanic’s settings are numbers in its file, such as JUMP: tune(2, 16) = 11. Project Settings › Mechanics shows them as sliders, and so does the inspector’s Mechanics tab while the game runs: drag one and the running game changes at once; let go and the number is written into the file, one step for Undo. Reset All puts a mechanic’s numbers back. With Run automatically off, the engine no longer runs the mechanic for you, and the page shows the line to call it from your update(). Your own scripts can have settings too: write NAME: tune(1, 10) = 5 # what it does, and they show under the file’s name.

When a mechanic finds something wrong in how it is called, the error shows at your line, in the mechanic’s words, with the mechanic’s own line underneath.

Sample games

Pyxen comes with finished games, with all their code and assets: real, playable games you can study, change, and learn from. Find them in Pyxen’s home, under Play and read. They open unsaved, so you can change anything; save one to keep your changes.

The home’s Snippets are short: one idea each, running, most of them in ten lines. Three are whole little programs to take apart: Pong, Game of Life and Particles.

A sample that grew from a starter says Make One Like This under it: it opens New Project with that starter chosen. Crownwood’s opens the Adventure starter, and Platformer’s the Platformer starter. Before you have any project, Continue shows the starters that make a good first game.

Platformer is the Platformer starter’s finished form: five levels painted in the Tilemap editor, one idea each. Spring Meadow has springs, Sky Bridge moving platforms, Locked Tower a key and a door, Slime Caves slimes to stomp and three hearts, and The Belfry a big bat to stomp three times.

Dungeon Survivors is ten minutes in the Moonlit Cellar: foes come in waves from every side, your weapons aim themselves, and each level up offers a choice of three. Its five weapons are in weapons.py, a function each, to read and change. Big Slimes leave chests: one holds a weapon’s evolution when the weapon is at level 8 and you keep its passive. At ten minutes the Slime King comes; puff it and the night is won.

Crownwood is an adventure with a sword, across six screens of meadow, wood and water: find the sword in the village, cut through the bushes, read the signs, and follow the crown east. The camera slides from screen to screen, and the game is saved each time you walk onto one. Its overworld is painted in the Tilemap editor, the hero, the foes and the hearts placed on its Things layer. In the East Wood, a cave leads down to the Slime Cellar, six rooms: a room whose shutters close until its last slime is gone, a key and a locked door, the Bombs (X, or the bomb button on a touch screen), which open cracked walls and rock for good, and the Big Slime, whose health is the bar along the bottom; beaten, it leaves a heart container. The cellar is painted in the Tilemap editor too.

Files and iCloud

Pyxen uses the standard iPadOS and macOS document model. Projects appear in Files on the iPad and in Finder on the Mac, alongside your other documents. If you have iCloud enabled, your projects sync automatically. On Windows, projects are files in File Explorer, like your other documents.

An account is optional, and Pyxen collects no telemetry. Your files stay where you put them.