Getting Started With PyTower ============================ Welcome to the PyTower user guide! Installation ------------ To start, ensure that PyTower is correctly installed. If the installation was a success, then you should be able to use the command ``pytower`` in terminal, and you should find the sub-directory tower-unite-suitebro in the main installation/repository folder, which contains a suitebro file format parser written in Rust by Brecert: https://github.com/brecert/tower-unite-suitebro For more info about the installation process, see :ref:`Installation Guide & Troubleshooting. ` General Usage ------------- When using PyTower, there are the following subcommands available to you: - ``pytower help``: PyTower help - ``pytower version``: PyTower version - ``pytower convert``: Convert between CondoData and .json - ``pytower backup``: (WIP) Canvas backup tool - ``pytower list``: List all detected tools - ``pytower info ``: Get detailed information about ```` - ``pytower scan ``: Scans path/directory for tool scripts - ``pytower run ...``: Run given tool - ``pytower fix``: Fix broken canvases and corruption in given file - ``pytower compress`` (WIP) Compression tool - ``pytower config``: PyTower configuration Example usages: - ``pytower help``: Displays help about PyTower - ``pytower info Tile``: Gets advanced info/help for tool "Tile" - ``pytower scan .``: Scans current directory for tool scripts to add - ``pytower run Rotate --output RotatedCondo --select group:4 -@ rotation=0,0,45 local=true``: Runs the "Rotate" tool with a group selection and passed-through parameters For any subcommand, leaving a requirement blank will bring up a help page. For example, running the command ``pytower run`` without any additional arguments will bring up a detailed help page generated by Python ``argparse``. Using ``pytower run`` --------------------- ``pytower run `` has the following arguments: - ````: Required positional parameter, replace this will the name of a tool! - ``-i``/``--input``: Input file to use (default: CondoData) - ``-o``/``--output``: Output file to use (default: CondoData_output) - ``-s``/``--select``: Selection mode to use (default: ``items``) - ``-v``/``--invert``: Flag to invert selection - ``-j``/``--json``: Flag to skip Suitebro parser steps - ``-@``/``--parameters``: Beginning of *tool parameters* To access your CondoData files, you need to first navigate to your Steam program files. From here, the path is typically given by ``Steam\userdata[steamid3]\394690\remote\Condos\``. Here you'll find folders that correspond to each condo type, for example ``WK_LevelEditor`` corresponds to the workshop level editor. Within each folder, there is CondoData (main currently active save) and folders for each snapshot taken, each with its own CondoData used when saving/loading a new snapshot. One current limitation of Tower Unite is that there's no way to hot-reload a map from disk. Even if you exit the condo and reenter it, the file from the start of the session will load instead. Therefore, whenever you make a change to CondoData, remember that the game must be exited and relaunched. For further discussion of this, see `Issue: Reloading Saves In-Game`__ .. _reload_issue: https://github.com/rainbowphysics/PyTower/issues/3 __ reload_issue_ By default, the ``--output`` filename will be the same as the input filename but with ``_output`` appended to the end. If you find this inconvenient, you can make PyTower overwrite a file instead by inputting the same value for ``--output`` as input. For example: ``pytower run center --input CondoData --output CondoData``. Just make sure you back-up your save in a snapshot or outside of Tower Unite before doing this! Selection Modes --------------- - ``items`` (default): Everything except property-only objects (CondoSettingsManager_2, Ultra_Dynamic_Sky_##, CondoWeather_2729, etc.)`` - ``name:``: Selects object by name (both custom name and internal object name) - ``customname:``: Select objects by custom name (name assigned in game) - ``objname:``: Select objects by internal object name only - ``group:``: Select objects by group id - ``random:``: Randomly selects objects with probability ``PROB`` - ``take:``: Randomly selects ``NUM`` number of objects - ``%``: Randomly select ``NUM`` percent of objects - ``box:,,/,,``: Select objects with position falling inside box - ``sphere:,,/``: Select objects with position falling inside sphere of radius ``R``. - ``all``: Everything including property-only objects - ``none``: Nothing (can be useful for generation tools) Selection Operators ~~~~~~~~~~~~~~~~~~~ Currently, the following selection operators are supported (in order of operator precedence): - Intersection ``*`` - Addition ``+`` - Difference ``\`` - Composition ``;`` Examples: - ``group:1+group:3``: Select group 1 and group 3 - ``group:42;10%``: Select 10% of objects in group 42 - ``name:CanvasWedge\group:5``: Select canvas wedges excluding group 5 .. note:: When inputting operators, it's important to not include any spaces. Spaces will be interpretted as additional arguments by argparse and break the ``pytower`` command. Tool Parameter Format --------------------- - Parameters are separated by spaces and have the format ``param=value``. Currently ``value`` must be a consecutive string of characters with no spaces or other forms of whitespace. - For example, ``pytower run MyTool -@ offset=0,0,300 foo=42`` passes two parameters to MyTool: ``offset`` with the value ``xyz(0,0,300)`` and ``foo`` with the value ``42``. - Each tool has its own parameters. Use ``tool info `` to bring up information about a tool's parameters