Skip to content

commands

FreeBodyEngine.cli.commands #

root_commands = [Command(['build', 'b'], build_handler, help_text='Build the project'), Command(['init', 'i'], init_handler, help_text='Initializes the project in the current directory, must be run before any other commands.'), Command(['run', 'r'], run_handler, help_text='Run a project.'), Command(['enter', 'e'], enter_handler, help_text='Enter the FreeBodyEngine environment.'), Command(['project', 'p'], subcommands=[Command(['list', 'l'], list_projects, help_text='List all projects in the registry.'), Command(['delete', 'd'], delete_project, help_text='Deletes a project.'), Command(['get', 'g'], get_project, help_text='Gets the project information.')], help_text='Commands to work with the FB Project system.'), Command(['create', 'c'], subcommands=[Command(['sprite', 's'], create_sprite, help_text='Create a new sprite.'), Command(['project', 'p'], create_project, help_text='Create a new project.'), Command(['font', 'f'], create_font, help_text='Create a font.')], help_text='Create a new resource'), Command(['log', 'l'], subcommands=[Command(['wipe', 'w'], log_wipe_handler, help_text='Permanantly wipes a log file.'), Command(['read', 'r'], log_read_handler, help_text='Reads a log file.')], help_text='Access and Modify project log files.'), Command(['help', 'h'], help_handler, help_text='Show help'), Command(['clear'], clear_handler, help_text='Clear the command line.'), Command(['cd'], cd_handler, help_text='Change to a directory.'), Command(['ls'], ls_handler, help_text='List files and sub-directories.'), Command(['cat'], cat_handler, help_text='Print the contents of a file.'), Command(['mkdir'], mkdir_handler, help_text='Create a directory.'), Command(['rm'], rm_handler, help_text='Remove a file or directory.'), Command(['fulcrum'], fulcrum_handler, help_text='A small text editor.'), Command(['compile_scripts', 'cs'], compile_handler, help_text='Compiles CPP scripts.'), Command(['cloc'], cloc_handler, help_text='Counts the lines of code in the current directory or specified project.'), Command(['cwoc'], cwoc_handler, help_text='Counts the words of code in the current directory or specified project.'), Command(['traceback', 'tb'], log_traceback_handler, help_text='Print the traceback for a log entry by ID.'), Command(['cowsay'], cowsay.cowsay_handler, help_text='A python port of the GNU/Linux CLI tool. Taken from https://github.com/VaasuDevanS/cowsay-python.')] module-attribute #

Command(names, handler=None, subcommands=None, help_text='') #

One CLI command or subcommand: a set of name aliases, an optional handler invoked as handler(env, args), and/or nested subcommands.

Stores the command's aliases, handler, subcommands and help text.

handler = handler instance-attribute #

help_text = help_text instance-attribute #

names = names instance-attribute #

subcommands = subcommands or [] instance-attribute #

find_subcommand(name) #

Returns the subcommand matching name, or None if there isn't one.

matches(name) #

True if name is one of this command's aliases.

print_help(path=[]) #

Prints this command's usage line, description and (if any) its subcommands. path is the chain of parent command names, used to build the usage line for a nested command.

Environment(path=None, project_id=None) #

The CLI's current working context: an on-disk path and, if that path (or a given project_id) resolves to a registered project, that project's id/path too. Also owns the file-watcher used while inside fb enter.

Resolves the project from project_id or path, in that order of precedence, falling back to the current working directory if neither is given.

observer = None instance-attribute #

path = None instance-attribute #

project_id = project_id instance-attribute #

project_path = None instance-attribute #

project_registry = ProjectRegistry() instance-attribute #

running = False instance-attribute #

detect_project() #

Returns the registry id of the project rooted at self.path, or None if there's no fbproject.toml there or it doesn't match a registered project name.

on_file_change(path) #

Called by the file watcher for every modified file; currently just logs the change to stdout.

reload_registry() #

Re-reads the project registry from disk, picking up projects added or removed since this Environment was created.

start() #

Starts watching the detected project directory for file changes, dispatching each one to on_file_change. No-op if no project was detected.

stop() #

Stops the file watcher started by start(), if one is running.

FileChangeHandler(env) #

Bases: FileSystemEventHandler

watchdog handler that forwards modified-file events to the owning Environment.

Stores the Environment to notify on a change.

env = env instance-attribute #

on_modified(event) #

Forwards the event to env.on_file_change(), ignoring directory-level events.

build_handler(env, args) #

fb build handler: builds the given project (or the detected one), passing --dev through as the dev-build flag. args is filtered down to its non-flag (non---...) entries before treating the first one as a project id - fb build --dev/fb build --web (no explicit project) used to fall into the "id given" branch with args[0] == "--dev"/ "--web" itself, looking up a project literally named that instead of correctly falling back to the detected one.

cat_handler(env, args) #

fb cat handler: prints the contents of a file relative to env.path.

cd_handler(env, args) #

fb cd handler: changes env.path to a directory relative to the current one, or - if given a registered project id instead of a path - jumps directly to that project's directory.

clear_handler(env, args) #

fb clear handler: clears the terminal screen using the platform-appropriate command.

cloc_handler(env, args) #

fb cloc handler: counts lines across engine-recognized source files (.cpp, .py, .fbusl, .fbvert, .fbfrag, .fbspr, .fbmat) under a project's main file/code/assets directories, or under a given/current directory, printing a per-extension breakdown plus totals.

confirm() #

Prompts for a y/N confirmation, returning True only on an explicit "y".

create_font(env, args) #

fb create font handler: generates an MSDF atlas (and its .fbfont metadata) from a .ttf file in the project's asset directory, writing both into a hidden .font folder alongside it.

create_project(env, args) #

fb create project handler: scaffolds a new project directory (assets/, code/, fbproject.toml, main.py), then cds into it and runs init_handler to register and compile it.

create_sprite(env, args) #

fb create sprite handler - currently just a placeholder that prints what it would create.

cwoc_handler(env, args) #

fb cwoc handler: same as cloc_handler, but counts words instead of lines.

delete_project(env, args) #

fb project delete handler: deletes a project's directory from disk after two confirmation prompts. Note: this does not remove the entry from the project registry, which is left pointing at a path that no longer exists.

dispatch(args, commands, env=None, path=[]) #

Resolves args against commands: aliases a leading fb/freebody to the implicit root (defaulting to help if nothing follows it), prints a matched command's help on a trailing --help/-h, recurses into subcommands, or invokes handler(env, args[1:]) once a leaf command is reached - creating a default Environment first if none was passed in.

enter_handler(env, args) #

fb enter handler: starts an interactive shell (prompt freebody@<project-or-path>>) that dispatches each typed line as its own CLI command against the same shared env/root_commands, until exit/quit is typed.

get_current_project(env) #

Returns the registry id of the project rooted at env.path (based on its fbproject.toml), or None if there's no fbproject.toml there or it isn't registered yet (printing a hint to run freebody init in the latter case).

get_json_log_file(env) #

Return path to the JSON log for the current project or environment.

get_log_file(env) #

Returns the plain-text log file path for the current project, under the OS-appropriate config directory (mirrors get_json_log_file, but for a log.txt - nothing in the engine currently writes to this path; only log.jsonl is actually produced by the logger).

get_project(env, args) #

fb project get handler: prints the id, name and path of the given project (or the current/detected one), if it exists.

get_project_lines(env, id) #

Counts the total lines across the project's main file and every .py file under its code directory.

help_handler(env, args) #

fb help handler: prints the list of top-level commands, then exits the process.

init_handler(env, args) #

fb init handler: registers the project rooted at the current working directory (not env.path - see the comment below) in the project registry, then runs the initial C++ compile for it.

lines_project(env, args) #

Prints the total line count (see get_project_lines) for the given project (or the current/detected one). Note: not currently wired into root_commands - cloc_handler (fb cloc) is the reachable equivalent.

list_projects(env, args) #

fb project list handler: prints a table of every project in the registry (id, name, path).

log_read_handler(env, args) #

Read the last N log entries from the JSON log file, optionally filtered by type.

log_traceback_handler(env, args) #

Print the traceback for a specific log entry by ID, colored like Python traceback, then show warnings/errors at the bottom.

log_wipe_handler(env, args) #

Wipe the JSON log file.

ls_handler(env, args) #

fb ls handler: lists the entries of a directory (default env.path), directories highlighted in blue.

main() #

CLI entry point (fb/freebody console script): builds an Environment from the current directory and dispatches sys.argv[1:] against the root commands.

mkdir_handler(env, args) #

fb mkdir handler: creates a directory relative to env.path, refusing to overwrite an existing path.

parse_options(args, allowed_flags=None) #

Separates flags (e.g. '-rf') from positional arguments. Returns: (set of flags, list of arguments)

rm_handler(env, args) #

fb rm handler: removes a file, or (with -r) a directory tree, prompting for confirmation unless -f is also given.

run_handler(env, args) #

fb run handler: runs the given project (or the detected one), swallowing Ctrl+C so stopping the game doesn't surface as a CLI traceback. args is filtered down to its non-flag entries before treating the first one as a project id - see build_handler()'s own comment for why (fb run --web hit exactly this: args[0] was "--web" itself, reported as a nonexistent project, instead of running the detected project with --web forwarded to run_project() via sys.argv, which is how it actually reads the flag - see dev/run.py's main()).