# ascii-scenery-assembler
A tool that helps with putting ascii sprites over each other.

## Guide

### Requirements
You need Python (3.10-ish or more recent recommended) and one of the following:

1. uv for easy and approved-by-me installation (if you're a Python dev and don't use uv, change that)
2. pipx for easy and better-than-pip installation
3. pip for easy installation (comes with Python, usually)
4. git for alternative installation

If you're not sure whether you have Python on your machine, type `python --version` in the terminal. If you get something like "no such command", go to https://python.org and get it from there.
Same for [uv](https://docs.astral.sh/uv/#installation), except without `--version`.

### Installation
To try it out using uv without installing, run `uvx asciiasm`. Or using pipx: `pipx run asciiasm`.

If you have uv: `uv tool install asciiasm`.

Else: [Install pipx](https://pipx.pypa.io/stable/#install-pipx) and run `pipx install asciiasm`.

If you don't want to install pipx, type `pip install asciiasm` in the terminal.

With git:
Type `git clone https://github.com/aal337/ascii-scenery-assembler.git` in the terminal, then `cd ascii-scenery-assembler`, then `pip install .`.

### Uninstallation

1. `uv tool uninstall asciiasm`
2. `pipx uninstall asciiasm`
3. `pip uninstall asciiasm`
4. Delete the directory `ascii-scenery-assembler` created by git and run `pip uninstall asciiasm`.

### Usage
1. Type `asciiasm` in the terminal.
2. Available commands:
    - `load sprite path/to/sprite.txt`
      where path/to/sprite.txt is the path to your sprite, which will be used as its name.
      Sprites currently have to be perfectly rectangular, including whitespace.
    - `place sprite layer row column`
      where layer is the number of the layer you want to put the sprite into, row the number of the row where the top left corner of the sprite should be, and column the number of the column. Rows/columns start at 0 and are counted from top to bottom/left to right.
      Layers start at 0, the higher the number, the further your sprite is 
    - save canvas path
      where path is the path at which you want to save your canvas.
3. End application:
    - CTRL + C
    - Type `exit tool`

The app will crash if you do something like opening a nonexistent file or placing a nonexisting sprite.
### Features
Currently, you may want to use something else with more QoL and customisation options. Analysing sprites to determine which whitespace fills a shape and which whitespace is outside of a shape to make the latter transparent is the main feature of this tool.
See also: https://summer.hackclub.com/projects/6906

## Disclaimer
I am not absolutely sure if everything works properly. Just take a look at the contents of the tests folder.
Your terminal could behave weirdly after usage.

## Contribution
If you've got feedback, send an email or open an issue.