The File System Dock

The File System dock shows the project's folders and files as Godot's FileSystem dock shows res://, and does to them what Godot's does: it opens, makes, renames, moves, copies and deletes them, keeping the project loading as they move; it filters and sorts them, keeps favorites, colours folders, shows previews in a split, and opens files and folders in other programs.

Paths in the dock are relative to the project's folder, with slashes, a folder's ending with one, as actors/player.scene and actors/; the project's own folder is ./. Folder colours are the project's, kept in project.pyssel so that everyone working on it sees them, as Godot keeps them in project.godot:

(pyssel/project:project-folder-colors
 (pyssel/project:load-project "~/games/arena/"))
;; => (("actors/" :RED) ("levels/" :TEAL))

The tree

At the top, Back and Forward go through the paths chosen, twenty at most; the path field shows the path chosen, and goes to a path typed in it; Change Split Mode splits the dock (below); and Refresh reads the files again, as Pyssel does not watch the file system. Under them are the filter and the sort menu, then the tree: Favorites, then the project's folder, its folders first, then its files, each with the icon of its kind, an SVG image with its own picture; names that start with a dot, as .pyssel/ and .git/, are left out. The main scene's name is in the accent colour. A double click or Return opens a file, as the editor opens files: a scene in a tab of its own, a resource in the Inspector, and Lisp and text in the Script screen; on a folder it folds or unfolds it.

• Filter Files, as Godot's: each word typed, split at spaces, must be in a name, case ignored; a folder that holds a match stays, unfolded, and the folders unfold as they were as the field empties. Its button clears it. Control+F in the dock goes to it.
• Sort, Godot's six: by name, by type (the extension, then the name) or by last change, each either way. Folders stay sorted by name, reversed with names.
• Favorites are each user's: Add to Favorites puts files and folders under Favorites, as does dropping them there, and Remove from Favorites takes them out. A favorite that is gone is dropped.
• Folder colours, Godot's nine, red, orange, yellow, green, teal, blue, purple, pink and gray: a coloured folder's icon is tinted and its row has a faint background of its colour, which the folders inside share and its files take darker. Set Folder Color is an edit of the project's history, saved at once.

The menu and the keys

A right click opens the menu of what can be done to the files and folders selected, as Godot's:

Item	For	What it does
Open Scene, Open	scenes, a file	Opens them, as a double click.
Set as Main Scene	a scene	Makes it the project's main scene.
Instantiate	scenes	Instances them in the scene shown, under the node selected.
Create New	one path	Makes a folder, a scene, a script, a resource or a text file in its folder (below).
Expand Folder, Expand Hierarchy, Collapse Hierarchy	folders	Unfolds them, or one and all inside it, or folds those.
Set Folder Color	folders	Colours them, or with Default (Reset) takes the colour away.
Copy Path, Copy Absolute Path	one path	Copies its path, or its absolute path, to the clipboard.
Rename	one path	Edits its name in place, the name selected but for its extension.
Duplicate	one path	Asks for a copy's name, beside it.
Move/Duplicate To	paths	Asks for a folder, and moves them there with Move, or copies them with Copy.
Delete	paths	Asks first, then moves them to the system's trash (below).
Add to Favorites, Remove from Favorites	paths	As above.
Show in FileSystem	a favorite	Shows it in the tree.
Open in Terminal	one path	Starts a terminal in its folder.
Open in External Program	a file	Opens it in another program.
Show in File Manager	one path	Shows it in the system's file manager.

The project's own folder is never renamed, moved or deleted, nor coloured. A right click on no item offers New Folder, New Scene, New Script, New Resource and New Text File in the folder chosen, Open in Terminal and Open in File Manager.

While the dock's tree or file list has the keyboard, Godot's keys are the dock's, so that the Scene dock's, as F2 and Control+D, do not reach it: Control+Shift+C copies the path, Control+Alt+C the absolute path, F2 renames, Control+D duplicates, Delete deletes, Control+Alt+T opens a terminal, Control+Alt+E an external program, Control+Alt+R the file manager, and Control+F goes to the filter. They are actions of the editor's input map, as :rename-file, which its settings change.

Moving, copying and renaming

Rename edits a name in place, refusing a name that is empty, holds a slash, a backslash or a colon, starts with a dot, or names a file there already. Files and folders dropped on a folder move into it, in the tree or the file list, but never into themselves. Where the folder has a name taken, a dialog lists the names and asks: Overwrite moves what was there to the system's trash first, Keep Both gives each its own name, as x (2).txt, and Cancel does nothing.

Pyssel's files refer to others by paths relative to themselves, so moving keeps the project loading:

• The scene and resource files that refer to what moved, and those moved that refer to what did not, are rewritten to refer to where the files are, their forms read and written without loading them.
• The resources loaded from moved files follow them, the same objects, as pyssel/resource:resource-file-moved says on Resources.
• The project's main scene, icon, autoloads and folder colours follow, and so do the favorites, the scenes open and the Script screen's pages.
• A Lisp file renamed or moved is renamed or moved in the :components of the game's system, in its .asd, as are those made and deleted: only the component's text changes, a new one going on a line of its own after the last, in the module whose folder holds it, named with slashes for the folders below, as (:file "actors/player"). A system whose components are computed or read conditionally is left as it is, and the Output dock says what to change.
• Lisp is not rewritten: the Output dock lists the lines of the project's Lisp that name a moved file by its old path, each a link to its line.

A copy, by Duplicate or Move/Duplicate To's Copy, refers to what its original does, and copies made together refer to each other. A Lisp file copied is added to no system, as it would define what its original defines again: the Output dock says how to add it.

Deleting

Delete asks first, as Godot's: it lists the files and folders to delete, and under "Dependencies of files to be deleted" each that other files refer to, with those files, which would no longer load. Remove moves them to the system's trash, where they can be restored from; the editor cannot undo it. The trash is the freedesktop.org trash on Linux and the BSDs, $XDG_DATA_HOME/Trash/ (~/.local/share/Trash/), or the .Trash-UID at the top of the file's mount where one exists; and the Recycle Bin on Windows. Then the project lets go of them: a main scene or icon deleted is unset, their folder colours and favorites are forgotten, an autoload that names a deleted scene is named in the Output dock, the scenes open of them close, those with changes not saved staying open as new scenes, and the Script screen's pages of them close but those with changes.

Making files

Create New makes in the folder of the path the menu opened for, or in the folder itself:

• Folder: a name, said valid or not as it is typed; slashes in it make folders below.

• Scene, by Godot's Create New Scene: its root a 2D Scene, a node-2d; a User Interface, a control; or Other, a class the Create New Node dialog picks; its name, and its root's, which an empty field takes from the scene's, boss_fight making BossFight. It is saved and opened.

• Script, by Godot's Create Script: the node class it inherits, as the game's package names it, a button picking one from the Create New Node dialog; the class's name, taken from the file's; a template; and the file's path. Create writes the file, adds it to the game's system, opens it in the Script screen and compiles it. The Node template, for actors/enemy.lisp:

  ;;;; enemy.lisp
  
  (in-package #:arena)
  
  (sc:define-node enemy (s2d:node-2d)
    ()
    (:documentation "Enemy."))
  
  (defmethod sc:ready ((enemy enemy))
    "Called when ENEMY enters the scene tree for the first time."
    (values))
  
  (defmethod sc:process ((enemy enemy) delta)
    "Called every frame, DELTA seconds after the frame before."
    (declare (ignore delta))
    (values))
  

  The Empty template is the in-package form alone.

• Resource: a resource class, from the Create New Node dialog made to list them, then the file's name; a new resource of the class is saved there and shown in the Inspector.

• Text File: a name, new_text_file.txt at first; the empty file opens in the Script screen.

Split mode

Change Split Mode goes from the tree alone to the tree over a file list, then beside it, and back, as Godot's. The tree then shows the folders, and the list what the folder chosen holds, .. first below the project's folder, then its folders and its files; or the favorites, with Favorites chosen. The list has its own filter, which searches the whole project, its own sort menu, and a button that shows it as thumbnails or as a list. It takes the menu, the keys, drags and drops, and renames in place, as the tree does.

Thumbnails are editor-settings-file-system-thumbnail-size units square, 64 by default, as Godot's, each a file's preview, or the large icon of its kind with its small icon at the corner. Previews are made as Godot makes them: an SVG image drawn; a scene drawn by the editor's engine into a texture of its own, the project's window as a play first shows it; a font's "Ab"; Lisp and text as Godot's script preview, two rows of pixels for each line, a pixel a character, in the Script screen's colours; their corners rounded. They are made a frame at a time and kept in the project's .pyssel/thumbnails/, by the file's path and write date, so a file changed gets a new one. Images Pyssel does not read yet, PNG among them, show their kind's icon.

Other programs

• Open in External Program opens a file in the program the editor's settings name for its kind: editor-settings-text-editor for Lisp, text, scenes and resources, editor-settings-vector-image-editor for SVG and editor-settings-raster-image-editor for other images; or, for "", as they are at first, in the program the system opens it with: xdg-open, else gio open, gvfs-open, kde-open5 or kde-open, and the shell on Windows.
• Show in File Manager opens the folder of a file, or the folder, in the system's file manager; on Windows, Explorer selects the file.
• Open in Terminal starts editor-settings-terminal-emulator in the folder, with editor-settings-terminal-emulator-flags, split at spaces, {directory} standing for the folder; or, for "", the first installed of gnome-terminal, konsole, xfce4-terminal, lxterminal, kitty, alacritty, urxvt and xterm, each given the folder as it takes it, and PowerShell on Windows.

The Output dock says so when no program opens.

What is kept

The project's .pyssel/editor.layout keeps, for each user, how the dock shows the files, as the layout's other parts are kept: the favorites, editor-layout-favorites; the mode, editor-layout-file-system-mode, :tree, :vertical or :horizontal; where its splits are, editor-layout-file-system-splits; the sort, editor-layout-file-sort; thumbnails or a list, editor-layout-file-list-mode; the folders unfolded, editor-layout-unfolded-folders; and the path chosen, editor-layout-file-system-path.