# Can't Believe It's Not SLADE

Can't Believe It's Not SLADE (CBINS) is a command line utility that allows users to easily create and manage PK3-based projects in more modern editors such as VSCode rather than SLADE.

It does this by providing the ability to create directory structures that can be opened in modern editors and tracked by source control such as Git, but then also providing the ability to compile that directory (including its ACS) into a PK3 file.

## [Download CBINS v1.1](https://trillster.dev/downloads/cbins-v1.1.zip)

## Basic Usage

To use CBINS, first start by creating a new folder for your project then place a copy of `cbins.exe` into it. Open that directory in a terminal by right-clicking then selecting `Open in Terminal`. This will allow you to enter the commands seen in the section below.

To start a new project, use the `cbins new` command like below:
```
cbins new name-of-project
```
This'll create an empty project with a default setup that's ready to be worked on in an editor such as VSCode. Just open the folder with a `-pk3` suffix that's created.

Once you've done your edits, you can use the `cbins build` command to create a PK3 like below:
```
cbins build
```

Once it's done building, you'll see it in the `dist` directory of your project structure!

You can additionally pass a `-o` parameter for CBINS to use `pngout.exe` to optimize the PNG files in your project. This may take a moment depending on the size of your project, so it is **not** default behavior.

Note that you'll have to install `pngout.exe` and place it into your project structure before that parameter will function fully. See the FAQ for more details there.

If you already have a PK3 that you wish to convert into a CBINS project, you can use a command that looks like below:
```
cbins new -pk3 "C:\Users\User\Desktop\Mega Man 8-Bit Deathmatch\wads\8bdm_jampacktwo-v2a.pk3" jampack-two
```

You can obtain the file path seen in this command by right-clicking a PK3 file then selecting `Copy as path`.

## Configuration

In every CBINS project structure that is created, there is a `cbins_config.json` file. This file holds some information for building a PK3 file and will typically look like below.
```json
{
	"folder": "project-pk3",
	"libraries": [
		"DTADD.acs",
		"BARLIB.acs",
		"ASSTLIB.acs"
	],
  "file_name": "project",
	"version": "v0a"
}
```

It is not recommended to modify the `folder` setting, but the `version` and `libraries` settings can be modified for differences in the build process. Adding new ACS files to the list of `libraries` will exclude those files from being compiled. Changing the value of `file_name` will change the name of the generated file. Changing the value of `version` will modify the version suffix added to the built file. The config above would generate a file with the name of `project-v0a.pk3`.

## Commands
```
cbins new [-h] [-v] [-pk3] project

positional arguments:
  project        name of project

options:
  -h, --help     show this help message and exit
  -v, --verbose  give detailed info
  -pk3           PK3 path to unpack into project

examples:
  cbins new unlimited-mp
  cbins new -pk3 "C:\Users\User\Desktop\Mega Man 8-Bit Deathmatch\wads\8bdm_jampacktwo-v2a.pk3" jampack-two
```
```
cbins build [-h] [-v] [-o]

options:
  -h, --help      show this help message and exit
  -v, --verbose   give detailed info
  -o, --optimize  optimize PNG files while building

examples:
  cbins build
  cbins build -v -o
```

## FAQ

**Why CBINS?**

SLADE is a good editor for starting projects and projects that find themselves on a smaller scale, but once projects become too big, many folks find themselves wanting to use modern editors. 

Additionally ZDoom and Zandronum's PK3 format by default doesn't lend well towards collaborative work or source control, so this utility aims to set up a directory structure which plays nicer with those. 

**Is this a full replacement for SLADE?**

No, this utility does not cover image offsetting which is one of the main perks of SLADE still. You can use SLADE for that purpose by opening the directories which this utility creates, allowing you to get the best of both.

Additionally, modern editors still do not tackle the problem of the WAD file type, so you will either need to open those in Ultimate Doom Builder or in SLADE still.

**Syntax highlighting?**

Unlike SLADE which has syntax highlighting for DECORATE and ACS by default, VSCode requires an extension for it. You can download one such extension [here](https://marketplace.visualstudio.com/items?itemName=kaptainmicila.gzdoom-zscript).

**Is this a full replacement for Doom Archive Manager?**

If you've been around the block, you may have heard of Doom Archive Manager (DAM) or been working on a project that has used it. This utility is not a full replacement for that tool either. This utility acts as an alternative to it focused on being more distributable as a single EXE and including features that lean towards how I personally use DAM.

**I get a warning when optimizing!**

If CBINS is unable to locate `pngout.exe` that means that either you haven't installed it or you've put it into the wrong location. You'll need to install `pngout.exe` from Ken Silverman's website [here](http://advsys.net/ken/utils.htm).

Make sure that you place the `pngout.exe` in the root of your project structure, the same directory as `cbins.exe`!

**I get an error when unpacking a PK3 into a project!**

Older versions of SLADE allow users to create PK3s that would traditionally be invalid in a normal file system. This includes duplicate files, invalid file names, and missing file extensions. This has historically caused unintended behavior and future versions of SLADE have fixed these issues.

However, for older projects, you may need to manually investigate the parts of the file which are invalid to a normal file system and manually correct them before being able to use CBINS.

## Source -> EXE Compilation

Create a virtual environment using the following command:
```
python -m venv venv
```
Activate the virtual environment using:
```
venv\Scripts\activate
```
Download requirements using the following command:
```
pip install -r requirements.txt
```
Use the following command to create an EXE file.
```
pyinstaller -F -n "cbins" -i "cbins.ico" src/main.py
```

## Accreditation

- Kudos to Russel for the original Doom Archive Manager that has helped development so much already and inspired this project.
- Credit to Ken Silverman for creating `pngout.exe` which this utility optionally uses for PNG optimization when building.
