Update README with more concise info and acknowledgements

This commit is contained in:
NGnius (Graham) 2020-06-08 20:24:50 -04:00
parent 34fdd0aefa
commit fe8ee1c262

View file

@ -1,19 +1,24 @@
# Pixi
Gamecraft mod for converting images into coloured blocks.
Think of it like automatic pixel art.
A mod for importing images and more into Gamecraft.
Developed by NGnius.
## Installation
Before installing Pixi, please patch Gamecraft with [GCIPA](https://git.exmods.org/modtainers/GCIPA/releases) and install the latest version of [GamecraftModdingAPI](https://git.exmods.org/modtainers/GamecraftModdingAPI/releases).
To install Pixi, copy `Pixi.dll` (from the latest release) into the `Plugins` folder in Gamecraft's main folder.
Once that's done, install Pixi by copying `Pixi.dll` (from the latest release) into the `Plugins` folder in Gamecraft's main folder.
Alternately, follow the install guide: https://www.exmods.org/guides/install.html (ignore the part about a zip file -- move Pixi.dll into the Plugins folder instead).
## Usage
Pixi adds new commands to Gamecraft's command line to import images (and more) into a game.
Since Pixi places vanilla Gamecraft blocks, imported images should be visible without Pixi installed.
Pixi adds new commands to Gamecraft's command line to import images, and other stuff, into a game.
Since Pixi places vanilla Gamecraft blocks, imported files should be visible without Pixi installed.
For the following section, anything between `[` and `]` characters is a command argument you must provide by replacing everything inside and including the square brackets.
An argument like `[dog name]` is an argument named "dog name" and could be a value like `Clifford` or `doggo`,
and `@"[dog name]"` could be a value like `@"Clifford"` or `@"doggo"`.
### Commands
@ -21,15 +26,11 @@ Since Pixi places vanilla Gamecraft blocks, imported images should be visible wi
`PixiConsole @"[image]" "[text block id]"` converts an image to text and places a console block beside you which changes the specified text block.
`Pixi2D @"[image]"` converts an image to blocks and places it beside you (along the xy-plane).
Anything between `[` and `]` characters is a command argument you must provide by replacing everything inside and including the square brackets.
An argument like `[dog name]` is an argument named "dog name" and could be a value like `Clifford` or `doggo`,
and `@"[dog name]"` could be a value like `@"Clifford"` or `@"doggo"`.
`Pixi2D @"[image]"` converts an image to blocks and places it beside you.
For example, if you want to add an image called `pixel_art.png`, stored in Gamecraft's installation directory,
execute the command `Pixi2D @"pixel_art.png"` to load the image as blocks.
It's important to include the file extension, since Pixi isn't psychic (yet).
It's important to include the file extension, since Pixi isn't capable of black magic (yet).
**EXPERIMENTAL**
@ -37,55 +38,47 @@ It's important to include the file extension, since Pixi isn't psychic (yet).
`PixiBotFile @"[bot]"` converts a `.bot` file from [rcbup](https://github.com/NGnius/rcbup) to blocks and places it beside you.
**NOTE**
For the preceeding commands, do not forget the `@"` before and `"` after the command argument, otherwise the command won't work.
If your image is not stored in the same folder as Gamecraft, you should specify the full filepath (eg `C:\path\to\image.png`) to the image.
This works best with `.PNG` images, but `.JPG` also works -- you just won't be able to use transparency-based features.
Optionally, if you know your command argument won't have a backslash `\` in it, you can omit the `@` symbol.
`PixiThicc [depth]` sets the block thickness for `Pixi2D` image conversion.
The depth should be a positive whole number, like 3 or 42, and not 3.14 or -42.
`PixiThicc [depth]` sets the block thickness, a positive integer value, for `Pixi2D` image conversion.
The default thickness is 1.
Some commands also have hidden features, like image rotation.
Talk to NGnius on the Exmods Discord server or read the Pixi's source code to figure that out.
### Behaviour
PixiText and PixiConsole share the same image conversion system.
The conversion system converts every pixel to a [color tag](http://digitalnativestudios.com/textmeshpro/docs/rich-text/#color) followed by a square text character.
Thanks to TextMeshPro's support for the full colour spectrum, colour accuracy for these commands is very good.
For PixiText, the resulting character string is set to the text field of the text block that the command places.
For PixiConsole, the character string is automatically set to a console block in the form `ChangeTextBlockCommand [text block id] [character string]`.
Due to limitations in Gamecraft, larger images will crash your game.
Pixi2D takes an image file and converts every pixel to a coloured block.
Unfortunately, an image file supports over 6 million colours and Gamecraft only has 100 paint colours (and only 90 are used by Pixi2D).
Pixi2D uses an algorithm to convert each pixel in an image into the closest paint colour, but colour accuracy will never be as good as a regular image.
Pixi2D's colour-conversion algorithm also uses pixel transparency so you can cut out shapes.
A pixel which has opacity of less than 50% will be ignored.
A pixel which has an opacity between 75% and 50% will be converted into a glass cube.
A pixel which has an opacity greater than 75% will be converted into an aluminium cube.
This only works with `.PNG` image files since the `.JPG` format doesn't store transparency.
A pixel which has an opacity greater than 75% will be converted into the block you're holding (or aluminium if you've got your hand selected).
This only works with `.PNG` image files since the `.JPG` format doesn't support image transparency.
Pixi2D also groups blocks together, since images have a lot of pixels.
After the colour-conversion algorithm, Pixi groups blocks in the same column with the same paint colour together.
The grouping algorithm reduces the block count by over 75% in ideal cases, and it can reduce the block count by 50% in most cases.
Imagine a standard 1080p screen (1920x1080 pixels), which has more than 2 million pixels.
Pixi2D could import that image with less than 500K blocks, which will still hurt Gamecraft's performance even on good PCs but it won't make it completely unusable like 2M blocks will.
Pixi2D also optimises block placement, since images have a lot of pixels.
The blocks grouping ratio is displayed in the command line output once image importing is completed.
PixiBot and PixiBotFile convert robot data to equivalent Gamecraft blocks.
If the conversion algorithm encounters a block it cannot convert, it will place a text block, with additional information, instead.
PixiBot uses the Factory to download robots, which involves a partial re-implementation of [rcbup](https://github.com/NGnius/rcbup).
Robot parsing uses information from [RobocraftAssembler](https://github.com/dddontshoot/RoboCraftAssembler).
## Suggestions and Bugs
If you find a bug or have an idea for an improvement to Pixi, please create an [issue](https://git.exmods.org/NGnius/Pixi/issues) with an in-depth description.
If you'd like to discuss your issue instead, talk to NGnius on the [Exmods Discord server](https://discord.gg/xjnFxQV).
PixiBot and PixiBotFile convert a robot to equivalent Gamecraft blocks.
If the conversion algorithm encounters a block it cannot convert, it will place a text block, with the block name, instead.
## Development
Show your love by offering your help!
### Ways To Contribute
- Build a Robocraft block that's not currently supported by Pixi (send it to NGnius on Discord).
- Report any bugs that you encounter while using Pixi.
- Report an idea for an improvement to Pixi or for a new file format.
For questions, concerns or reports, please contact NGnius in the [Exmods Discord server](https://discord.exmods.org).
### Setup
Pixi's development environment is similar to most Gamecraft mods, since it's based on HelloModdingWorld's configuration.
@ -98,7 +91,7 @@ You can make sure Pixi can find all `.dll` files it needs by copying your Gamecr
To avoid that, create a symbolic link (look it up) to your Gamecraft install folder named `ref` in this folder instead.
Like most mods, you will have to patch your game with [GCIPA](https://git.exmods.org/modtainers/GCIPA).
Pixi also requires the [GamecraftModdingAPI](https://git.exmods.org/modtainers/GamecraftModdingAPI) library to be installed (in `ref/Plugins/GamecraftModdingAPI.dll`).
Pixi also requires the [GamecraftModdingAPI](https://git.exmods.org/modtainers/GamecraftModdingAPI) library to be installed (in `ref/Plugins/GamecraftModdingAPI.dll`, the usual place).
### Building
@ -106,14 +99,24 @@ After you've completed the setup, open the solution file `Pixi.sln` in your pref
I'd recommend Visual Studio Community Edition or JetBrains Rider for Windows and Monodevelop for Linux.
If you've successfully completed setup, you should be able to build the Pixi project without errors.
If it doesn't work and you can't figure out why, ask for help on the [Exmods Discord server](https://discord.gg/xjnFxQV).
If it doesn't work and you can't figure out why, ask for help on the [Exmods Discord server](https://discord.gg/2CtWzZT).
# Acknowledgements
PixiBot uses the Factory to download robots, which involves a partial re-implementation of [rcbup](https://github.com/NGnius/rcbup).
Robot parsing uses information from [RobocraftAssembler](https://github.com/dddontshoot/RoboCraftAssembler).
Gamecraft interactions use the [GamecraftModdingAPI](https://git.exmods.org/modtainers/GamecraftModdingAPI).
Thanks to **TheGreenGoblin** and his Python app for converting images to coloured square characters, which inspired the PixiConsole and PixiText commands.
Thanks to **Mr. Rotor** for all of the Robocraft blocks used in the PixiBot and PixiBotFile commands.
# Disclaimer
Pixi, Exmods and NGnius are not endorsed or supported by Gamecraft or FreeJam.
Modify Gamecraft at your own risk.
Read the LICENSE file for licensing information.
Please don't sue this project's contributors (that's what all disclaimers boil down to, right?).
Please don't sue this project or its contributors (that's what all disclaimers boil down to, right?).
Pixi is not a psychic overlord which secretly rules the world.
Well, not this world at least.
Pixi is not magic and is actually just sufficiently advanced technology that's indistinguishable from magic.