RFC: Designing the successor to ue4cli (unreal-cli)

[adamrehn]

Hi community,

Over the past few months I've been thinking about the current design of ue4cli and considering ways in which it could be improved. The existing structure evolved organically from a very small base of initial commands that focussed pretty much exclusively on improving the Unreal Engine developer experience under Linux and providing the foundation for what would eventually become conan-ue4cli, and things have gotten a little messy as the scope of the tool has grown. There are also features that the community has expressed an interest in (e.g. fine-grained control of how ue4cli selects the Unreal Engine installation to use when working with individual projects or plugins) that are difficult to implement due to design decisions that were made very early in the development of ue4cli, along with structural issues inside the codebase that make supporting multiple versions of the Unreal Engine awkward in the long run.

Although these issues could be addressed by a major refactor and breaking changes to the command-line interface, I've decided that it's cleaner to simply rewrite the project as a separate tool. Creating a separate tool also gives me the opportunity to remove the number 4 from the name, since Unreal Engine 5 is coming up soon and I'd like to support both UE4 and UE5 within the same codebase (and hopefully UE6, UE7, etc. when we eventually get to that point.) The new tool will be called unreal-cli, and a repository exists here with initial boilerplate: https://github.com/adamrehn/unreal-cli.

My plan is that unreal-cli will be a Python command-line tool in the same manner as ue4cli, but with commands structured in the two-level style popular with larger command-line tools such as the CLI tools for major cloud providers (e.g. the AWS CLI, Azure CLI, Google Cloud SDK, etc.), all of which also happen to be written in Python. This involves a two-level hierarchy of commands that explicitly groups related commands, accompanied by a set of global flags recognised by all commands.

To make configuration as flexible as possible, my plan is to style the configuration of unreal-cli after profile/context based systems such as Conan profiles, Docker contexts, kubectl contexts, etc. The idea is that the tool maintains a set of named configuration profiles and users can add/update/delete profiles by name, with each profile stored as a JSON/YAML file in a filesystem directory that can be copied across machines if needed. Users can select a default profile to use when running all commands, or use a global flag recognised by all commands in the form of --profile=PROFILE to specify the profile to use for an individual run of a command without needing to modify the user's default profile selection. (This is particularly handy if you need to run multiple commands in parallel with different configuration profiles, since you're not touching any shared state.)

The most important setting in a configuration profile will be the Engine selection behaviour for the profile. I'm currently planning to include the following options:

• Auto-detect the location of the latest Installed Build of the Unreal Engine available on the system (the default behaviour of ue4cli today if an override has not been set with the ue4 setroot command.)

• Use a specific Unreal Engine installation at a particular path (the behaviour of ue4cli today when an override has been set with the ue4 setroot command.)

• Auto-detect the version number specified in the .uproject file in the current working directory at the point that a project-related command is run (or the .uproject file of the containing project when running a plugin-related command on a plugin nested inside a project), and then use UnrealVersionSelector to locate the registered Unreal Engine installation for that version number. The user will also need to specify a fallback behaviour to use when not working with a project (or a plugin nested in a project), which will be one of the other options listed above.

Here are some of the commands that I'm planning to include, grouped using the two-level hierarchy:

# These subcommands work with Unreal projects, and act like the equivalent descriptor commands from ue4cli
ue project build [ARGS] [--profile=PROFILE]
ue project clean [ARGS] [--profile=PROFILE]
ue project generate [ARGS] [--profile=PROFILE]
ue project package [ARGS] [--profile=PROFILE]
ue project run [ARGS] [--profile=PROFILE]
ue project test [ARGS] [--profile=PROFILE]

# These subcommands work with Unreal plugins, and act like the equivalent descriptor commands from ue4cli
ue plugin build [ARGS] [--profile=PROFILE]
ue plugin clean [ARGS] [--profile=PROFILE]
ue plugin generate [ARGS] [--profile=PROFILE]
ue plugin package [ARGS] [--profile=PROFILE]

# These subcommands work with the Unreal Engine itself, and act like the equivalent commands from throughout ue4cli
ue engine root [--profile=PROFILE]
ue engine version [--profile=PROFILE]
ue engine editor [ARGS FOR UE4EDITOR] [--profile=PROFILE]
ue engine uat [ARGS FOR UAT] [--profile=PROFILE]
ue engine build <TARGET> [CONFIGURATION] [ARGS FOR UBT] [--profile=PROFILE]
ue engine clean <TARGET> [CONFIGURATION] [ARGS FOR UBT] [--profile=PROFILE]
ue engine libs [--profile=PROFILE] ???

# These subcommands manipulate unreal-cli configuration profiles
ue profile list
ue profile select <PROFILE>
ue profile create <PROFILE> [-OPTION=VALUE] [-OPTION=VALUE] [...]
ue profile delete <PROFILE>
ue profile update <PROFILE> [-OPTION=VALUE] [-OPTION=VALUE] [...]

# This is basically just to have an equivalent to `ue4 clearcache` from ue4cli
ue cache clear

Please let me know what you think, and if there are any issues you can identify that I haven't considered here!

[adamrehn]

@ImmortalEmperor @lukehb @TBBle

[sleeptightAnsiC]

Will propose some draft on this topic after all the fixes on ue4cli are done.

However, very first thing that comes to my mind is that a lot of command repetition can be avoided with optional argument. Especially something like [engine|plugin|project] would be already possible to implement in ue4cli and implicitly detected based on current working directory. Few commands from ue4cli already does something similar for ue4 build and ue4 package, but does not allow to explicitly chose it which is a bit of pain.

Anyway, that would be just a proposal.