# Liquorice

![](logo.png "Liquorice Logo")

*Liquorice* is a system for constructing maps for the [computer game Doom](https://doomwiki.org/wiki/Doom) by writing algorithms to describe the geometry. A *Liquorice* program is a series of instructions to move a virtual "turtle" or "pen", which define the walls, floors, rooms and monsters as it goes.

More specifically, *Liquorice* is an embedded domain-specific language (eDSL) within the pure functional programming language [Haskell](https://www.haskell.org/).

## Quick example

    -- simple example, triangle (for orientation); unique texture per line
    import Liquorice.Monad
    import Liquorice.Render

    main = buildWad "example1.wad" $ runWadL $ do
        mid "ZZWOLF1"
        draw 128 0
        mid "ZZWOLF2"
        draw 0 128
        turnaround
        mid "ZZWOLF3"
        draw 128 128
        rightsector 0 128 160
        turnaround
        step 64 32
        thing

## More detailed example

See [examples/birds.hs](examples/birds.hs), for an example program
that generates a complete playable map. The map targets Doom 1 / The
Ultimate Doom (map slot E2M8), and requires a doom engine with raised
engine limits, such as [Crispy Doom](https://www.chocolate-doom.org/wiki/Crispy_Doom).

The generated PWAD, with nodes, ready to play: [birds.zip](https://redmars.org/liquorice/birds.zip)

*birds.hs* is a re-implementation/transformation of ["Bird Cage"
for WadC](https://redmars.org/wadc/examples/#_birds_wl).

## Getting Started

### For Doom novices

Doom's engine source code was open-sourced in 1996, but you need a copy of
the game's data files to use them. You can buy [The Ultimate Doom](https://www.gog.com/game/the_ultimate_doom) and [Doom II](https://www.gog.com/game/doom_ii_final_doom) at [Gog](http://www.gog.com/), amongst other places. Failing that, you could try [FreeDoom](https://freedoom.github.io/), a free-content game for Doom engines.

Examples of powerful open source engines include [Crispy Doom](https://www.chocolate-doom.org/wiki/index.php/Crispy_Doom), [Eternity Engine](http://eternity.youfailit.net/wiki/Main_Page) and [GZDoom](https://zdoom.org/index).

### For Haskell novices

…

## Evaluation

The commands that a typical *Liquorice* program will use are predominantly
monadic, and so make use of Haskell's "do-notation" for ordering. Internally,
the majority of these monadic functions are wrappers around pure equivalents
which transform an input `Context` type into an output, e.g.:

    xoff :: Int -> Context -> Context
    xoff x c = c { paletteXoff = x }

    place :: Int -> Int -> (Context -> Context) -> Context -> Context
    place x y fn c = c & step x y
                       & fn
                       & step (-1 * x) (-1 * y)

The pure functions can be combined using the infix operator `&` (from
`Data.Function`), or the more usual composition operator (which reads
back-to-front). However, the monadic versions are probably more user-
friendly, and so the separate pure implementations might go away or
stop being explicitly exported at some point. We also probably need to
use the monadic versions if we want to introduce randomness or debug IO
in the middle of a program.

A series of monadic Liquorice statements are converted into a final `Context`
via `runWadL`. A `Context` is written to an output PWAD file via

    buildWad :: FilePath -> Context -> IO ()

Internally, `buildWad` first converts a `Context` into an intermediate data
structure `WadMap`, which closely resembles the binary structure of a PWAD.
(`WadMap` itself is a specialisation of `Wad`, imposing the presence of map
 specific lumps)


## Pros/Cons

Pros:

* Unlike WadC, you have full access to the Context at any point in your
  program, which you can inspect or transform as you wish.
* You also have the full power of the Haskell programming language.
* In particular simply infix numeric operators are hugely useful.

Cons:

* There's no GUI.
* The Pure-versus-Monadic functions are a bit awkward and I might get rid of the
pure versions altogether in the future
* There are some slow parts (line splitting in particular)
* If you don't know Haskell, this will be very hard to use and most error messages
will make little sense.
* You need a Haskell development environment installed to use *Liquorice*.

## Code overview

The following three source files are the ones that you will want to import
as modules to your Liquorice program:

 * `Liquorice.hs` — The main `Context` definition and most basic pure operations
 * `Liquorice/Monad.hs` — monadic wrappers around the above, + some more
 * `Liquorice/Render.hs` — exports `buildWad` for exporting a PWAD

These are back-end implementation details:

 * `Liquorice/Pure.hs` — most of the "standard library", in pure functions
 * `Liquorice/Line.hs` — `Line` type, line splitting and tests
 * `Liquorice/Wad.hs` — Wad and WadMap definitions and binary serialisation
 * `TestMain.hs` — HTF test harness

## Author

*Liquorice* was created by [Jonathan Dowland](https://jmtd.net/) and is
distributed under the terms of the GNU Public License, version 3 (see
[COPYING](COPYING)).

The design of *Liquorice* is heavily
influenced by [Wad Language (WadC)](https://jmtd.net/wadc/), which in turn owes
a debt to [LOGO](http://el.media.mit.edu/logo-foundation/what_is_logo/logo_programming.html).

## See also

 * [Jonathan Dowland's homepage](https://jmtd.net/)
 * [WadC](https://jmtd.net/wadc/)
 * [The Doom Wiki](https://doomwiki.org/)