Micro-Machinations (MM) is a game design language for describing economic game mechanics. The Micro-Machinations Library (MM Lib) enables game designers to modify game mechanics while a game is running. Here you can learn about playing with MM, modeling MM, using MM Lib and building MM Lib. More information will be provided here as it becomes available.
| Directory | Platform | Description |
|---|---|---|
| mm/mm | C++ | The MM library currently requires STL, Flex and Bison. |
| mm/LibMM | C++ .NET | Wraps the MM library for usage with Microsoft .NET |
| mm/doc | Contains an early reference manual and a game prototype | |
| mm/tests | MM | Contains textual Micro-Machinations examples |
AdapTower is an academic game prototype in the tower defense genre that embeds the MM Libary. It was created with the Foundations of Digital Games (FDG) paper "Adapting Game Mechanics with Micro-Machinations" [4]. The paper describes a series of modifications to the game's mechanics using visual MM. Here we provide the game and the equivalent textual MM it interprets. The game and its mods were demoed live at FDG using these presentation slides [5]. You can download the game and try it out for yourself.
Installing AdapTower. AdapTower runs on Windows and requires the .NET and XNA frameworks.
| Download | Description |
|---|---|
| AdapTower.zip | Contains AdapTower binaries, DLLs and MM models. |
| Microsoft .NET Framework 4.5 | AdapTower runs on the Microsoft .NET Framework. |
| Microsoft XNA Framework Redistributable 4.0 | AdapTower is built using the XNA Framework. |
| Microsoft DirectX 9c | DirectX is likely already installed. Run dxdiag to be sure. |
Running AdapTower. When running the game, a right click creates a tower and a left click creates a base. Hit ESC for viewing the MM state, and click the next button to evaluate the next modification. Click on a tower or base to view its MM values. Edit files for making your own modifications. Run AdapTower from the Command Prompt or hit ~ (tilde) for opening the builtin debug console for viewing messages passed from the MM Lib.
Kudos: AdapTower is based on Phantom, an Entity Component based Game Engine for XNA 4.0 developed at Dutch game business Ludomotion.
Note: We plan to make the sources of AdapTower available here.
For modeling MM knowledge about the language is required. Machinations were originally only intended for game design [1] and have evolved into Micro-Machinations, which were first formally analyzed [3] and now also used in software development [4]. Please note that the Flash based Machinations tool [2] relates to the prior work. Since we currently lack a graphical MM editor, writing MM on a whiteboard and then translating manually to textual MM is advised. For now, we provide a grammar of MM, which provides syntax highlighting in Rascal, a meta-programming language and language workbench based on Eclipse [6]. A more comprehensive IDE called Micro-Machinations Analysis in Rascal (MM AiR) will be made available here later.
Below is the Machinations logo, textual MM in a Rascal IDE that encode the logo diagram and a table showing the resource amounts in pool p and flow f over time steps.
| state | pool p amount | flow f amount |
|---|---|---|
| 0 | 7 | 7 |
| 1 | 14 | 14 |
| 2 | 28 | 28 |
| 3 | 56 | 56 |
The MM Library is provided under the 3-clause BSD license.
Warning: Please note that the MM Library is an academic prototype, and as such has not undergone rigorous industrial testing. Using the library comes at your own risk.
/******************************************************************************
* Copyright (c) 2013-2014, Amsterdam University of Applied Sciences (HvA) and
* Centrum Wiskunde & Informatica (CWI)
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
* 3. Neither the name of the copyright holder nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* Contributors:
* * Riemer van Rozen - rozen@cwi.nl - HvA / CWI
******************************************************************************/
An early reference manual generated by Doxygen is provided here [7].
Note: The API is still being improved and a How-To document is not yet available.
Users can build the MM Library on MacOS and Windows.
MacOS
- For MacOS we provide the XCode project mm.xcodeproj.
- Flex and Bison are part of XCode, the scanner and the parser are regenerated automatically.
Windows
- For Windows we provide the Visual Studio 2010 LibMM wrapper project.
- Flex and Bison are not required, precompiled sources of the scanner and parser are included.
[1] J. Dormans. Engineering Emergence. PhD Dissertation. Universiteit van Amsterdam, 2012. (Website / PDF)
[2] J. Dormans. Machinations: Game Feedback Diagrams. http://www.jorisdormans.nl/machinations, 2013.
[3] P. Klint and R. van Rozen. Micro-Machinations -A DSL for Game Economies. In M. Erwig, R. Paige, and E. Wyk, editors, Software Language Engineering, volume 8225 of Lecture Notes in Computer Science, pages 36–55. Springer International Publishing, 2013. (Website / PDF)
[4] R. van Rozen and J. Dormans. Adapting Game Mechanics with Micro-Machinations. In Foundations of Digital Games, 2014. (Website / PDF)
[5] R. van Rozen. Adapting Game Mechanics with Micro-Machinations. Presentation Slides. Presented at Foundations of Digital Games, 2014. (PDF)
[6] CWI SWAT group. Rascal MPL. http://www.rascal-mpl.org, 2014.
[7] R. van Rozen. Micro-Machinations Manual. GitHub, 2014. (PDF)
Status:
- Made MM available under 3-clause BSD license.
Next steps:
- Testing
- regression test setup
- reuse examples used to test MM-AiR
- Evaluator: add features
- gate
- Machine: manage all instances
- maps and vectors
- Simplify external API as done with AdapTower C# wrapper.
- Documentation
- DoxyGen
- Architecture, design decisions
Status:
- Evaluator
- Pool, Source, Drain, Flow edge, Trigger and Condition are working
- Converters: seem to be working.
- RefNodes and Aliases: seem to be working.
- Instance Pools
- new feature that allows pools of objects (they do not flow between pools)
- Reflector: working, transforms types
- add and replace work okay
- update is still tricky
- Instances: observes definitions
- Declarations: observe definitions create InterfaceNodes, edges are resolved to these nodes
- Machine: tracks objects it owns
- Parser / Grammar: flex/bison working
- Includes type transformations using "modify" keyword
- Includes data transformations using "step" keyword
- Identifiers are lexicals that are post-processed
- Grammar has zero conflicts