Skip to main content

CLI

After installing WASM-4, you can use its Command Line Interface (CLI) to perform various tasks.

The w4 command#

Summary:

The w4 command is the base for all further subcommands.

Usage:

w4 [OPTIONS]w4 <COMMAND> [OPTIONS] [TARGET]

Examples:

w4                        # Shows the helpw4 --version              # Shows the versionw4 new --odin snake       # Create a new projectw4 init --go              # Create a new project in current folderw4 run build/cart.wasm    # Run build/cart.wasm in the browser

Options:

OptionDefault valueDescription
-VShows the version of the w4 CLI
--versionSame as -V

Description:

Like a lot of modern CLI tools, the w4 CLI provides several subcommands like new, build or run. Executing it alone will show the default help to get a feel for how to interact with it.

By providing the -V or --version the output will be replaced with the currently installed version.

new, create and init#

Summary:

The new, create and init commands create a new WASM-4 project with the selected language.

Usage:

w4 new [OPTIONS] <NAME>w4 create [OPTIONS] <NAME>w4 init [OPTIONS]

Examples:

w4 new snakew4 new --odin tictactoew4 initw4 init --lang nim

Options:

OptionDefault valueDescription
--asUses AssemblyScript for the new project
--assemblyscriptSame as --as
--cUses C/C++ for the new project
--dUses D for the new project
--goUses Go for the new project
--neluaUses Nelua for the new project
--nimUses Nim for the new project
--odinUses Odin for the new project
--porthUses Porth for the new project
--rolandUses Roland for the new project
--rsUses Rust for the new project
--rustSame as --rs
--watUses WebAssembly Text for the new project
--zigUses Zig for the new project
--lang LANGUAGEas / W4_LANGUses the provided language

Description:

By default, new and init create an AssemblyScript project. This can be changed by providing one of the language options like --as, --c, --d, --lang go etc.

It's also possible to set the default language for the current user or the whole system by setting up the environment variable W4_LANG.

Example (Linux):

# ~/.profileexport W4_LANG=odin # Set default language for new WASM-4 projects to Odin

Difference between new, create and init#

All commands provide the same options and they all create a new project. The difference is, new creates a new directory while init uses the current directory. The create command is simply an alias for new.

watch#

Summary:

The watch command starts the build process and starts a server. This can be accessed in a browser. Changes made to the code, will cause a rebuild and a refresh of the browser.

Usage:

w4 watch [OPTIONS]

Examples:

w4 watchw4 watch -nw4 watch --no-open

Options:

OptionDefault valueDescription
-nPrevents the browser from opening
--no-openSame as -n
--openForces a new browser tab or window (Default)
--qrGenerates a QR code in the terminal (Default)
--no-qrPrevents the generation of a QR code
--port4444Binds the command to the given port

Description:

By default, the command starts the build process (npm run build, make etc.), starts a server and opens the browser. The option -n/--no-open prevents the browser from opening.

Another default behavior is the generation of a QR code in the terminal. This can be useful to test games on other devices such as mobile phones. The option --no-qr prevents this from happening. This can be useful in case the terminal can't display QR codes.

The --port option allows to bind the command on a specific port. The default port is 4444. In case, w4 is unable to bind to the given port, it tries to find an available port in the next 1000 higher ports. Should this also fail, the execution will be stopped and an error will be presented to notify the user.

It's also possible to set those options by setting an environment variable for the current user or the whole system. The corresponding variables are W4_NO_OPEN, W4_NO_QR and W4_PORT. Setting it to any value activates them.

Example (Linux):

# ~/.profileexport W4_NO_OPEN=1 # Disable the browser from openingexport W4_NO_QR=1   # Disable the generation of QR codesexport W4_PORT=8080 # Use port 8080 instead of port 4444

run#

Summary:

The run command opens a cartridge in the web runtime.

Usage:

w4 run [OPTIONS] <CART>

Examples:

w4 run carts/wormhole.wasmw4 run -n carts/minesweeper.wasmw4 run --no-open carts/watris.wasm

Options:

w4 run has the same options as w4 watch

Description:

The command starts the web runtime in a local server.

Unlike the w4 watch command, the w4 run command doesn't start the build process.

Aside from that difference, it behaves the same as w4 watch.

run-native#

Summary:

The run-native command opens the cart in the native runtime.

Usage:

w4 run-native <CART>

Examples:

w4 run-native carts/wormhole.wasmw4 run-native carts/minesweeper.wasmw4 run-native carts/watris.wasm

Options:

There are additional options.

Description:

The command opens the cartridge in a native window. The performance may be higher than using the web-runtime.

png2src#

Summary:

The png2src command converts PNG images to source code.

Usage:

w4 png2src [OPTIONS] <IMAGES...>

Examples:

w4 png2src fruit.pngw4 png2src --odin wall.pngw4 png2src --lang rust top.png down.png left.png right.png

Options:

OptionDefault valueDescription
--asGenerates AssemblyScript source
--assemblyscriptSame as --as
--cGenerates C/C++ source
--dGenerates D source
--goGenerates Go source
--neluaGenerates Nelua source
--nimGenerates Nim source
--odinGenerates Odin source
--porthGenerates Porth source
--rocGenerates Roc source
--rolandGenerates Roland source
--rsGenerates Rust source
--rustSame as --rs
--watGenerates WebAssembly Text source
--zigGenerates Zig source
--lang LANGUAGEas / W4_LANGGenerates source in the provided language
-t FILEUses a custom template file
--template FILESame as -t
-o FILEUse given file instead of stdout
--output FILESame as -o

Description:

The command takes one or more PNG image(s) and converts them to source code. The images have to meet certain criteria. Those are:

  • Color Mode must be "Indexed"
  • Max 4 colors
  • At least 8 in width and 8 pixels in height (Recommended)

Using an image that is not index or has more than 4 colors will cause an error. Images with the size of 4x4 or less might lead to bugs.

By default it uses AssemblyScript. But this can be changed by setting the environment variable W4_LANG. Check the description of new, create and init for more details.

It also writes the output to the standard output (stdout). Usually this is the terminal executing w4 png2src. This can be changed by providing the -o/--output option.

The template file has to use Mustache. More about this can be found in Docs/Guides/Sprites/Custom template.

bundle#

Summary:

The bundle command bundles a cartridge for final distribution.

Usage:

w4 bundle <OPTIONS> <CART>

Examples:

w4 bundle --html watris.html --title Watris --description "The classic puzzle game" --icon-file "watris.png" carts/watris.wasmw4 bundle --linux minesweeper carts/minesweeper.wasmw4 bundle --windows wormhole.exe --title "Wormhole Deluxe" wormhole.wasm

Options:

OptionDefault valueDescription
--html OUTPUTBundle standalone HTML file
--windows OUTPUTBundle a native Windows executable
--mac OUTPUTBundle a native macOS executable
--linux OUTPUTBundle a native Linux executable
--title TITLE"WASM-4 Game"Title of the game
--description DESCRIPTIONThe description of the game
--icon-file FILEIcon of the game. Supported are png, ico and svg.
This will override --icon-url
--icon-url URLURL to the the Favicon of the game
--timestampfalseAdds build timestamp to output
--html-template FILEbuilt-in templateMustache HTML template file for standalone HTML.

Description:

With the bundle command, it's possible to distribute a cartridge to the web, windows, linux and macOS. Each are self contained and therefore easy share.

The --title option changes the visible title of the game. Like in the title bar of the window.

note

At least one of the targets (--html, --windows, --linux, --mac) must be provided. If no target is provided, the command will fail.

help#

Summary:

The help commands provides more details about the w4 CLI and its tools.

Usage:

w4 help [COMMAND]w4 help [OPTION]

Examples:

w4 helpw4 help png2srcw4 help run-native

Options:

OptionDefault valueDescription
-VShows the version of the w4 CLI
--versionSame as -V

Description:

This command shows all options, the usage and more about the w4 CLI or its subcommands. Providing the -V or --version option however has precedence over a subcommand.

Therefore a w4 help --version png2src will not lead to show the help for the png2src command, but will only output the current version.