### ----------------------------------------------------
### -- MUGS
### -- Licenses: Artistic-2.0
### -- Authors: Geoffrey Broadwell
### -- File: docs/announce/v0.1.2.md
### ----------------------------------------------------
% 0.1.2 Release


# MUGS 0.1.2 Released!

The [Raku-MUGS org](https://github.com/Raku-MUGS) is proud to present our
second development release on the way to our next major milestone.  This
release includes many changes since 0.1.1 to address feedback from our users in
`#mugs` in IRC, but the majority of the milestone work is yet to be done.  :-)


## Packaging

MUGS is available in both source and package form, via these methods:


### `zef`

To simply play with what's already there, use `zef` to install all of `MUGS`
from the `zef/fez` ecosystem.  To prevent failure due to an **unneeded**
transitive dependency that does not exist on all systems, use the following
command:

```
zef install --exclude="pq:ver<5>:from<native>" MUGS
```

**NOTE 1:** If you're having trouble with installing via `zef`, please take
a look at our [installation guide](../howto/install-mugs.md), which has
additional troubleshooting hints.

**NOTE 2:** In this release, MUGS-UI-WebSimple is known to be broken when
installed by `zef`, because it cannot find its HTML templates.  If you would
like to try this UI, please use the Source Repos method below.


### Source Repos

The source for all released MUGS repos can be found in the
[Raku-MUGS org on GitHub](https://github.com/Raku-MUGS).  Note that if you are
working on a UI repo, you will probably want to install MUGS with `zef` as
described above to satisfy dependencies, or at least install both
[MUGS-Core](https://github.com/Raku-MUGS/MUGS-Core) and
[MUGS-Games](https://github.com/Raku-MUGS/MUGS-Games).


### Docker

MUGS does not yet have prebuilt Docker packages, but each source repo includes
two `Dockerfile` scripts.  The main `Dockerfile` simply installs the relevant
MUGS libraries, scripts, and resources on top of a `rakudo-star` official image
and creates a default MUGS identity universe.  `Dockerfile.test` builds on that
by also installing test identities into the default universe.


## JSON → CBOR

The single largest change in 0.1.2 is the switch of message serialization from
JSON to CBOR, based on the new
[TinyFloats](https://github.com/japhb/TinyFloats),
[CBOR::Simple](https://github.com/japhb/CBOR-Simple), and
[Cro::CBOR](https://github.com/japhb/Cro-CBOR) modules, all of which were
written from scratch to support this transition (but released separately).

This change allows for *much* more efficient handling of packed binary data,
much more data in each server message without overwhelming network bandwidth,
and allows a much richer data model on the wire.

This was made possible by the recent
[Cro 0.8.5 release](https://cro.services/docs/releases), which includes
performance and developer enhancements supporting these changes; MUGS now
depends on that (or later) Cro release.

**NOTE 1:** As a side effect of the richer data model, some data will be coming through in
native (or in the case of enums, numeric) format, rather than converted to
strings as with JSON.  You may be assuming receipt of string data in some
places; expect to undo any workarounds you may have added.  (This has already
been fixed in several places in the core MUGS repos.)

**NOTE 2:** In order to provide easier-to-read debugging output, some debug code
outputs messages in prettified JSON format, which as mentioned above can't
represent the full richness of CBOR data.  This
[JSON::Fast PR](https://github.com/timo/json_fast/pull/73)
will at least prevent debug output failures; if you're having debug issues,
~~apply the JSON::Fast PR, reinstall it, and try again.~~
**UPDATE: The PR has been merged, just upgrade to JSON::Fast 0.16 or later.**


## Other Improvements

After the 0.1.1 development release, the members of `#mugs` on IRC offered
excellent feedback on issues great and small.  There is still much to do to
address it all, but together with the JSON → CBOR transition discussed above,
the following represents a mini-milestone in that direction:


### Bug Fixes

* Fix a race condition in game client/UI startup
* Don't create a second lobby client if directly entering lobby
* Slightly improve invalid structure error messages
* Support more terminal types in MUGS::UI::CLI::Input (which previously could
  hang after displaying a prompt on some terminals)
* Fix "Use of Nil in string context in sub escape-text" warnings in WebSimple UI
* Switch to newer `client.my-winloss()` method for determining winloss status
  in WebSimple UI


### Documentation

* Add GOTCHAS section to MUGS-UI-WebSimple README for issues found by `#mugs`
  folks that could not be completely fixed in this release
* Add top-level MUGS repo [docs/ README](../README.md)
* How To
  * Add new [docs/howto/](../howto/) tree
  * Move [Release Guide](../howto/release-guide.md) to docs/howto/
  * Add [Installing MUGS](../howto/install-mugs.md) guide
  * Add **WIP** [Port a Game](../howto/port-a-game.md) and
    [Create a UI](../howto/create-a-ui.md) guides
* Design
  * Add [Game Classes orientation doc](../design/game-classes.md)
  * Add [Data Validation design doc](../design/validation.md)
  * Add [Supporting "Bullet Hell" Games rumination doc](../design/bullet-hell.md)
  * Add [Logo Ideas historical doc](../design/logo.md)
  * Add **WIP** [Life of a UI](../design/life-of-a-ui.md) and
    [Life of a Request](../design/life-of-a-request.md) docs


### Genres and Games

* Start implementing PFX "game", testing performance of server-managed particle
  effects (finally possible with the JSON → CBOR serialization transition)
* Add a simple UI for the PFX test "game" in MUGS-UI-TUI (`mugs-tui pfx`)
* Stub in the beginnings of the CardGame genre


### Logging/Telemetry

* Track creation Instant for Message objects
* Add GameStateUpdate as first Log::Timeline::Task in Server
* Switch --debug default to False (off) for `mugs-ws-server` and
  `mugs-web-simple`


### Performance

* Depend on Cro 0.8.5+ to get significant WebSocket performance improvements
* Much faster and perf-stable StructureValidator
* Support fast path for validating packed arrays (where the message decoder
  itself guarantees that all elements match the array element type)


## Contributions

This development release is largely the work of Geoffrey Broadwell (`japhb` on
Libera.Chat and [GitHub](https://github.com/japhb)), based on excellent feedback
on the [0.1.1 release](v0.1.1.md) from the denizens of `#mugs` in IRC.

If you'd like to contribute to future releases, please take a look at
[our CONTRIBUTING doc](../CONTRIBUTING.md); we'd love to have you!


## Contacting Us

We are on the `#mugs` channel on Libera.Chat IRC; please come and ask questions or
offer suggestions!  Please note that we do not yet have 24-hour round-the-clock
coverage, so please stick around and allow some time for response if you don't
get one immediately.

If you are interested in the more general world of game development on Raku,
we are also on the `#raku-gamedev` channel, also on Libera.Chat IRC.


## Future

The next few milestones have been sketched out in our
[release roadmap](../todo/release-roadmap.md).  Future releases are of
course subject to change, but the most likely changes are deferral of iffy
changes or incomplete features that are holding up release of finished work.


## Thank You

THANK YOU to the ever-helpful `#mugs` crew, to everyone who worked on the many
[projects on which MUGS is built](../design/built-with.md), to the awesome and
supportive Raku community, and of course to Larry, Damian, Jonathan, and all
the other Raku designers for creating a language that brings joy day after day!


