Projects and Screens

Projects and screens

Project files

A project is one file with the extension .wysicraftproj. It holds all your screens, scripts (including ones you haven't assigned yet) and images.

• File → New project (Ctrl+N) starts a blank project. You're asked to save unsaved changes first.
• File → Open project or pack… (Ctrl+O) opens a .wysicraftproj. It can also open older formats: a project.json folder or an exported .wysicraft pack. When you save one of those, Wysicraft asks for a new .wysicraftproj rather than overwriting the old files.
• File → Save (Ctrl+S) and Save as… (Ctrl+Shift+S). Saving is atomic: if something goes wrong while writing, your previous file stays intact.
• Double-clicking a .wysicraftproj opens it if you ticked file registration in the installer.

Project files contain your server script source. Only share them with people who should see that code. The files you give players are exports; see Exporting and installing.

Project settings

Project → Project settings…

Setting	Meaning
Name	Display name.
Id	Lowercase ID used for commands (/<id>.open, /<id>.close), the JAR name and image paths. Changing it moves your images to the new name automatically.
Author, Version	Metadata. Version is major.minor.patch.
RuntimeVersion	Oldest Wysicraft runtime your project needs. Exports set this for you.
GridSize, Snap	Canvas grid spacing and whether moves snap to it.
Dependencies	Mod IDs that must be installed (for example kubejs). Minecraft refuses to load the project without them.

Recovering unsaved work

Every 30 seconds, changed work is saved to a separate recovery draft in %LOCALAPPDATA%\Wysicraft\Recovery, including unsaved text in the script editor. Autosave never overwrites your real project file, and it runs in the background so the editor doesn't pause.

After a crash or power loss, choose File → Recover unsaved project…, pick the draft, then Save as to keep it. Drafts from other Wysicraft windows that are still open aren't listed. Saving normally, or choosing not to save, removes the draft.

Screens

A project can have up to 128 screens. The dropdown above the canvas switches between them.

• New screen adds one. IDs are lowercase letters, numbers and underscores, and unique within the project.
• Delete screen removes the current screen after asking which screen should replace it in links and as the Main screen. It can be undone. You must keep at least one screen. A screen used as an Item List row template must be reassigned first. Screen IDs written inside your JavaScript must be updated by hand.
• Screen settings clears the selection and shows everything about the current screen in Properties, with its Open/Close events in Events.

Component sources (see Reusable components) aren't listed in the screen dropdown. You edit them from the Components panel.

Screen settings

Setting	Meaning
Screen ID	The screen's ID. Changing it updates built-in links (open_ui actions), the Main screen, row templates and components. IDs written inside scripts are not changed. Press Enter or click away to apply.
Title	Title shown in the screen frame, if the frame is on.
Width, Height	Design size in GUI pixels (16–4096). Controls anchored right, bottom, center or stretch move as you change it.
Main screen	The screen /<project id>.open opens. Ticking it on one screen removes it from the previous one.
Variables	Starting values for screen variables, written name=value;name=value. Scripts, conditions and ${name} text use them.
Responsive layout	In Minecraft, controls move by their anchors when the game window is a different size. See [[Anchors and responsive layouts
Show frame / title	Draws Minecraft's opaque screen frame and title behind your controls. Off by default.
Dim game behind UI	Darkens the world behind the screen. Off by default.
Fit to viewport	For non-responsive screens, scales the whole screen down if it's larger than the game window.

Transparent screens: turn off both frame and dimming, and add a Panel wherever you want a background. The canvas's grey backdrop is only a workspace aid; it isn't exported.

How screens open in Minecraft

Each project automatically gets two commands:

• /<project id>.open opens the project's Main screen for you.
• /<project id>.close closes the project's screen for you.
• Add a player name (/<id>.open Steve) to target another player. That needs permission level 2, so it works from command blocks and the server console.

Other ways in:

• /wysicraft open <screen> or /wysicraft open <project>:<screen> opens a specific screen. /wui is a short alias.
• An open_ui action or ui.open() in a server script navigates between screens. See Events and actions.
• Mods and KubeJS can open screens; see Addon API.

Two projects can both have a screen called main. Internally, screens are addressed as project_id:screen_id.