shmup/playscii
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add a cheatsheet

Browse source
This commit is contained in:
Jared Miller 2026-02-13 20:05:23 -05:00
parent aa6af42381
commit 95188581bb
Signed by: shmup
GPG key ID: 22B5C6D66A38B06C
1 changed files with 279 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

279
docs/cheatsheet.md Normal file
View file

@ -0,0 +1,279 @@
# playscii cheatsheet
## hotkeys
### file operations
| key | action |
| ------ | ------------------------- |
| Ctrl+N | new art |
| Ctrl+O | open art |
| Ctrl+S | save |
| Ctrl+W | close art |
| Ctrl+M | import file |
| Ctrl+E | export (last used format) |
| Ctrl+Q | quit |
### tools
| key | tool |
| --- | ----------------- |
| A | paint (pencil) |
| E | erase |
| R | rotate |
| Q | grab (eyedropper) |
| T | text |
| S | select |
| V | paste |
| I | fill |
### painting & tile properties
| key | action |
| ----------- | ------------------------------------------------- |
| 1 / 2 | decrease / increase brush size |
| 3 | cycle character forward (Shift+3 backward) |
| 4 | cycle foreground color forward (Shift+4 backward) |
| 5 | cycle background color forward (Shift+5 backward) |
| 6 | cycle transform forward (Shift+6 backward) |
| C | toggle affects: character |
| F | toggle affects: foreground color |
| B | toggle affects: background color |
| X | toggle affects: transform |
| W | swap foreground / background colors |
| Space | toggle picker popup (charset + palette) |
| Return | paint / confirm |
| Right-click | quick grab (sample tile under cursor) |
### selection
| key | action |
| ------------------ | ------------------------------- |
| Ctrl+A | select all |
| Ctrl+D | select none |
| Ctrl+I | invert selection |
| Ctrl+X | cut |
| Ctrl+C | copy |
| Ctrl+V | paste |
| Delete / Backspace | erase selection (or entire art) |
| Shift+Return | add to selection |
| Ctrl+Return | remove from selection |
### view & camera
| key | action |
| ----------------- | ----------------------------- |
| Shift+Z | zoom in |
| Shift+X | zoom out |
| = / - | pixel-exact zoom in / out |
| Z | snap zoom to fit art (toggle) |
| Shift+Arrow keys | pan camera |
| Middle mouse drag | pan camera |
| Scroll wheel | zoom in / out |
| Home | center cursor in art |
| Shift+G | toggle grid |
| Shift+R | toggle CRT filter |
| Shift+T | toggle camera tilt |
| Shift+U | toggle UI |
| Shift+I | toggle overlay image |
| Alt+Return | toggle fullscreen |
| Ctrl+= / Ctrl+- | increase / decrease UI scale |
### layers & frames
| key | action |
| -------------- | -------------------------------------------------------- |
| [ / ] | previous / next layer |
| , / . | previous / next frame |
| P | toggle animation playback |
| L | cycle inactive layer visibility (visible / dim / hidden) |
| O | toggle onion skin |
| Ctrl+Tab | next art document |
| Shift+Ctrl+Tab | previous art document |
### art operations
| key | action |
| ------------ | -------------------- |
| Ctrl+R | resize art |
| Ctrl+K | crop to selection |
| Ctrl+H | choose character set |
| Ctrl+P | choose palette |
| Ctrl+T | run last artscript |
| Ctrl+Z | undo |
| Shift+Ctrl+Z | redo |
### game mode
| key | action |
| ----------------- | ---------------------------------- |
| G | toggle game mode |
| Shift+E | toggle game edit UI |
| F2 | reset game (reload last state) |
| Ctrl+G | load game state |
| Ctrl+S | save game state |
| Ctrl+Shift+G | set game directory |
| Ctrl+L | select objects |
| Ctrl+P | choose spawn object class |
| Arrow keys / WASD | move player |
| Shift+Arrow keys | move selected objects |
| Z | grab (hold) |
| X | frob (interact / attack) |
| F3 | toggle collision on selected |
| F5 | toggle all origin visualization |
| F6 | toggle all bounds visualization |
| F7 | toggle all collision visualization |
### debug & console
| key | action |
| ------------ | ------------------------- |
| ` (backtick) | toggle developer console |
| F1 | open help docs |
| F8 | toggle debug text overlay |
| F9 | toggle FPS counter |
### menu access
Alt + first letter opens each menu:
F(ile), E(dit), T(ool), V(iew), A(rt), R(frame), L(ayer),
C(har/color), G(ame), H(elp), S(tate), W(orld), O(bject)
## how to do things
### painting basics
1. pick a tool: A for paint, E for erase, T for text
2. pick a character: press 3 to cycle, or hold Space to open the picker
3. pick colors: press 4 (foreground) or 5 (background) to cycle, or
use the picker — left-click sets foreground, right-click sets background
4. paint: click and drag, or press Return
5. use C/F/B/X to toggle which properties the tool affects — handy for
recoloring without changing characters, or vice versa
### using the picker
- press or hold Space to open it
- top section: character swatch (click to select)
- middle section: color swatch (left-click = foreground, right-click = background)
- bottom section: transform selector (flip X/Y, rotate 0/90/180/270)
- the picker also has tabs for tool settings
- Ctrl+H to change character set, Ctrl+P to change palette
### working with layers
- ] to go to next layer, [ for previous
- layers have Z-depth for parallax (change via Layer menu)
- L cycles how inactive layers display: full / dim / invisible
- add layers from the Layer menu
- each layer is independent — tools only affect the active layer
### working with frames (animation)
- . for next frame, , for previous
- P to play/stop animation
- O to toggle onion skin (shows ghost of adjacent frames)
- add frames from the Frame menu — you can set hold times per frame
- frames share the same layers
### import and export
**importing:**
- Ctrl+M to import
- supported: ANSI (.ans), plain text (.txt), bitmaps (.png/.jpg/.bmp/.gif),
EDSCII, ENDOOM (.lmp)
- bitmap import converts images to ASCII art using the current charset+palette
**exporting:**
- Ctrl+E to export (uses last format), or File → Export for format picker
- supported: ANSI (.ans), plain text (.txt), PNG image, animated GIF,
PNG sequence, ENDOOM (.lmp)
- PNG export has scale and CRT filter options
### bitmap to ASCII conversion
1. File → Import (Ctrl+M)
2. select a bitmap image (.png, .jpg, .bmp, .gif)
3. playscii converts it using the current charset and palette
4. try different charsets (Ctrl+H) for different looks
5. "2-color bitmap" import option for 1-bit black/white conversion
### custom character sets
1. create a PNG spritesheet of your characters
2. create a matching .char file with metadata (character width/height, map)
3. drop both in `charsets/` directory
4. select via Ctrl+H or the picker
### custom palettes
- drop an image file in `palettes/` — colors are sampled from it
- or use Art → Palette from image to generate one from any image
- select via Ctrl+P or the picker
### artscripts (generative art)
- python scripts that procedurally modify art (.arsc files)
- live in `artscripts/` directory
- Art → Run Artscript (Ctrl+T runs the last one)
- scripts use a `TileIter` helper to iterate over all tiles
- useful for patterns, noise, cellular automata, etc.
### game mode basics
1. press G to enter game mode
2. games are folders with `art/`, `scripts/`, `sounds/`, and a `start.gs` state file
3. Game → New game to create a project, or Game → Open game to load one
4. objects are Python classes extending `GameObject`
5. edit object properties by clicking them in the editor (Shift+E to show edit UI)
6. Ctrl+P to spawn new objects from the object class list
7. F2 to reset to last saved state — essential for rapid iteration
### developer console
- press ` (backtick) to open
- type `help` for available commands
- run arbitrary python — useful variables:
- `app` — the application
- `world` — the game world
- `player` — the player object
- `camera` — the camera
- `art` — the current art
- `ui` — the UI
- `sel` — selected objects
- `hud` — the game HUD
### rapid iteration workflow
**for art:**
- edit → Ctrl+S to save → switch to game mode (G) to see changes live
**for games:**
- edit scripts in your text editor
- Ctrl+S to save game state
- F2 to reload — instant feedback loop
- use the console (`) for live debugging and tuning
- expose tunable values in the Properties Editor for in-app tweaking
### configuration
- config files live in OS-specific locations:
- linux: `~/.config/Playscii/`
- macOS: `~/Library/Application Support/Playscii/`
- windows: `C:\Users\<you>\AppData\Local\Playscii\`
- `playscii.cfg` — app settings
- `binds.cfg` — custom keybindings (copy from `binds.cfg.default` to customize)
### mouse controls
| input | action |
| -------------------- | ------------------------ |
| left click + drag | use current tool |
| right click | quick grab (sample tile) |
| middle click + drag | pan camera |
| scroll wheel | zoom in / out |
| scroll wheel (on UI) | scroll UI elements |