# craftlang

Craftlang (`.craft` files) is an expression language for crafting
recipies and block arrangement in the popular free software block
building game [Minetest](https://minetest.org).  This tool is capable
of parsing `.craft` files and generating image outputs.

## Usage

This tool is written in [Raku](https://raku.org) and such you need to
have `rakudo` installed on your system.  Additionally you need to make
your minetest assets tree and environment files available via
ennvironment variables.

```console
$ craftlangc ./path-to-recipe.mtcraft --env=/path/to/environments \
      --assets=/path/to/minetest/assets/root
```


## Language overview

Craftlang is a domain-specific language for expressing recipes, based
on a small set of keywords, with associated payloads.  A payload is
either a primitive or scope.  Scopes use two-space indentation to
handle end-of-scope separation.

### Example

The following example should be enough to explain the basic structure
of primary mtcraft files.

```mtcraft
ENV alloys
INPUTS
  copper_ingot 7
  tin_ingot 1
OUTPUTS
  bronze_ingot 8
```

The `ENV` keyword loads an environment file.  Environment files add a
set of metadata which is added to a generated output, and also
provides a way to specify how other keywords are handled.

The `INPUTS` and `OUTPUTS` keywords open scopes.  A scope is a set of
statements that is specific to the loaded environment but must be one
of the following: `key-value`, `marker` or `keyword`.

The example above contains three `key-value` statements.  A `marker`
statement does not contain additional data and instead provides a
boolean flag to the environment.  A `keyword` statement provides a way
to have nested `ENV`, `INPUTS`, and `OUTPUTS` scopes.


### Environment files

The environment provided via the `ENV` keyword must be present as a
`.craftenv` file in the provided `ENV` parameter.  An environment
specifies the input-output mappings for `INPUTS` and `OUTPUTS` scopes.

Required keywords for an ENV file are `BG`, `INPUTS`, `MODE`, and
`OUTPUTS`.  The `SPACING` keyword is permitted outside of the `INPUTS`
and `OUTPUTS` blocks to be applied to both simultaniously.  The `MODE`
keyword selects the general output mode.  Currently accepted modes are
`crafting` and `arrangement`

```mtcraftenv
BG alloy_furnace
MODE crafting
SPACING 15 15
INPUTS
  ANCHOR 125 125
  COUNT 2 1
OUTPUTS
  ANCHOR 525 125
  COUNT 1 1
```

The default fill-mode is Left-to-right-top-to-bottom.