From 95188581bb8c49b91f511b2762543dcc6ea5e946 Mon Sep 17 00:00:00 2001 From: Jared Miller Date: Fri, 13 Feb 2026 20:05:23 -0500 Subject: [PATCH] Add a cheatsheet --- docs/cheatsheet.md | 279 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 docs/cheatsheet.md diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md new file mode 100644 index 0000000..925c8c6 --- /dev/null +++ b/docs/cheatsheet.md @@ -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\\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 |