magicum
- Latin: the nominative neuter singular of magicus.
magicus
- magic, magical.
magicum is a libre Magic: The Gathering game rules engine implementation, written in Clojure.
This project is currently in a very early development stage, so there is not much functionality to be seen... yet ;-)
IPA^(key): /'ma.ʝi.kum/, [ˈma.ʝɪ.kʊm]
Whereas the original Classical Latin word should be pronounced /ˈma.ɡi.kum/ or [ˈma.ɡɪ.kʊm], as the origin language of the original game's name is English, we use an English-like pronunciation.
When released, this project will follow the version scheme MAJOR.MINOR.COMMITS, where MAJOR and MINOR provide some relative indication of the size of the change, but do not follow semantic versioning, and COMMITS is an ever-increasing counter of commits since the beginning of this repository.
In general, after release all changes will endeavor to be non-breaking (by moving to new names rather than by breaking existing names). For a more detailed rationale, please refer to Rich Hickey's "spec-ulation Keynote" from Clojure/conj 2016.
Latest release: (none yet)
https://github.com/allentiak/magicum.
FIXME: explanation
$ java -jar magicum-x.y.z-standalone.jar [args]
FIXME: listing of options this app accepts.
FIXME: app invocation examples.
At this point, probably too many. To be discovered! :-)
-
Use advanced programming techniques, such as formal specifications, and property-based and generative testing as much as possible.
Luckily, Clojure comes "with batteries
includedready-to-plug-when-needed", so it has these features already available, through clojure.spec and test.check :-) -
Base the aforementioned specifications on the most recent version of the Magic Comprehensive Rules, as published by the Magic copyright holders. As a reference, you will find a copy of the latest version used in /doc/third-party.
-
Stand on the shoulders of giants: use Systematic Program Design and (Functional) Domain-Driven Development to strive for achieving a Clean Architecture.
Systematic Program Design is (greatly!) explained with both depth and simplicity in "How to Design Programs, Second Edition", by Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram Krishnamurthi.
A Functional take on Domain-Driven Development is (excellently!) shown in "Domain Modeling made Functional", by Scott Wlaschin.
The Clean Architecture is (very entertainingly!) described in "The Clean Architecture", by Robert C. Martin (a.k.a. "Uncle Bob").
This program is inspired by other Magic: The Gathering libre implementations. It's great being able to get inspiration from these great, already-working projects!
Luckily, we have tried them all, read their code, and even made (minor) contributions to some of them.
And we continue to use a couple of them regularly, as each one of them has one thing we appreciate.
More specifically, we are referring to (in discovery order):
| Implementation (Backend + Frontend) | Strongest point |
|---|---|
| Magarena (Java + Swing) | The only that fully implements an state-of-the-art MCTS AI. |
| XMage (Java + Swing) | The best (OO) architectured. |
| Matag (Java + JavaScript) | The best in-game UI, by far. |
| MvS' Magic (Haskell) | Written in a fully-functional language, with a Client/Server architecture. |
| Forge (Java + Swing) | Best overall out-game UI design, and gameplay features. |
As I couldn't find any FP Magic implementation written in Clojure, and given that I want to give clojure.spec a try, I set up to write my own.
Of course, I was not the first one to come up with the idea of using clojure.spec for this. The domain specs are based on Robert Stuttaford's and Adam Frey's work, with their express permission to use their code as I see fit. For more details, see doc/ABOUT_THE_SPECS.md. You will find a copy of the latest Magic Comprehensive Rules document on which the specs are based in the folder /resources/third-party.
Copyright © 2020, Leandro Doctors.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
Additional permission under GNU AGPL version 3 section 7:
If you modify this Program, or any covered work, by linking or combining it with Clojure (or a modified version of that library), containing parts covered under the same terms as Clojure (currently, the Eclipse Public License version 1.0), the licensors of this Program grant you additional permission to convey the resulting work. Corresponding Source for a non-source form of such a combination shall include the source code for the parts of Clojure used as well as that of the covered work.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/.
All third-party trademarks and/or registered trademarks mentioned in this program and/or its documentation are the property of their own owners. We are not affiliated in any way with the copyright owners of the official Magic: The Gathering game implementations (neither digital or analog), nor we claim any copyright over their products, their art assets or any other kind of intellectual wealth of theirs. What's theirs, is theirs. What's ours, is ours. In case of doubt, please feel free to contact us - either via email or by opening a ticket ("issue").