Skip to content

Workspace appearance

Choose a world and adjust spacing or motion. Saved settings go in client.toml; see Configuration for its location.

Choose a world

[world]
path = "flat-2d"

Use flat-3d for depth effects. Hardware-rendered desktops default to Flat 3D; Android, iOS, and software rendering default to Flat 2D.

Flat 2D and Flat 3D come with the app. You can also add downloaded worlds.

Add a downloaded world

A downloaded world is a folder named after the world's id, holding <id>.pck and <id>.json side by side. Graffitty lists every world it finds in the worlds folder of its data directory:

~/.local/share/graffitty/worlds/
└── <id>/
    ├── <id>.pck
    └── <id>.json

If XDG_DATA_HOME is set, use $XDG_DATA_HOME/graffitty/worlds instead (see Desktop file locations).

  1. Download the world's zip. Pick the release made for your Graffitty version.
  2. Extract it into the worlds folder.
  3. Restart Graffitty and choose the world under View → World.

Only install worlds from sources you trust: a world runs scripts inside Graffitty.

Example: Bistro

Bistro is an official downloadable world: a night-time Paris street and café with your panes placed through the scene (about 400 MB). Download bistro-world-<version>.zip from its latest release, then extract it.

macOS and Linux:

mkdir -p ~/.local/share/graffitty/worlds
unzip ~/Downloads/bistro-world-*.zip -d ~/.local/share/graffitty/worlds

Windows (PowerShell):

$worlds = "$HOME\.local\share\graffitty\worlds"
New-Item -ItemType Directory -Force $worlds | Out-Null
Expand-Archive "$HOME\Downloads\bistro-world-*.zip" $worlds

This gives worlds/bistro/bistro.pck, bistro.json, and LICENSE.txt. Restart Graffitty and choose View → World → Bistro.

Start in a downloaded world

To open a downloaded world instead of your current default, set path to its id in client.toml and restart. For Bistro:

[world]
path = "bistro"

A value without / or a .pck suffix names an installed world by id. To load a pack from somewhere else, give its path instead, for example "%(data)/worlds/bistro/bistro.pck" (see Paths in client.toml). Tune a world's panes under [worlds.<id>] in World settings.

Update or remove a downloaded world

App updates don't update downloaded worlds. To update one, delete its folder (for example ~/.local/share/graffitty/worlds/bistro), extract the new zip, and restart. Always replace the .pck and .json together.

To remove a world, delete its folder and any path line naming it. If a world fails to load, Graffitty falls back to its built-in world.

Adjust pane spacing

[tiling]
gap = 8

[worlds.flat-2d.terminal_window]
padding = [8, 8, 8, 8]
corner_radius = 12

Padding runs left, top, right, bottom. Use worlds.flat-3d for Flat 3D. Set gap or corner radius to 0 for no gap or square corners.

Zoom and pan

  • Pinch, or Cmd+scroll on macOS / Ctrl+scroll elsewhere, to zoom.
  • Right-button drag to pan.
  • Choose View → Main Area to reset framing.

Each tab remembers its view. Rename panes and tabs with gft rename-pane and gft rename-tab; omit the name to resume automatic titles.

Reduce motion or frame rate

Choose View → Tab Transition / Session Transition → None to stop transition motion. See the effects gallery for other choices.

[window]
max_fps = 60
inactive_max_fps = 30

Both caps accept 1–240; the inactive cap cannot exceed the active cap. Display refresh and VSync can limit the actual rate.

See World settings for per-world overrides, backdrop blur, and transition configuration. Use letter and dust settings for session-flight tuning.