mirror of
https://github.com/Cockatrice/Cockatrice.git
synced 2026-11-13 05:20:00 -08:00
Replace upstream README with honest Continuumatrice product, build and license documentation
This commit is contained in:
Christian Daniel Jensen
parent
e2e07296dc
commit
6d7f263021
1 changed files with 43 additions and 163 deletions
206
README.md
206
README.md
|
|
@ -1,188 +1,68 @@
|
|||
<p align='center'><img src=https://cloud.githubusercontent.com/assets/9874850/7516775/b00b8e36-f4d1-11e4-8da4-3df294d01f86.png></p>
|
||||
# Continuumatrice
|
||||
|
||||
---
|
||||
**Continuumatrice** is a standalone, open-source desktop card-game client for **Continuum Universes**, developed by **Continuum Universes Studio** and based on the Cockatrice C++/Qt project.
|
||||
|
||||
<p align='center'>
|
||||
<a href="#cockatrice"><b>Cockatrice</b></a> <b>|</b>
|
||||
<a href="#download-">Download</a> <b>|</b>
|
||||
<a href="#related-repositories">Related</a> <b>|</b>
|
||||
<a href="#community-resources-">Community</a> <b>|</b>
|
||||
<a href="#contribute">Contribute</a> <b>|</b>
|
||||
<a href="#build--">Build</a> <b>|</b>
|
||||
<a href="#run">Run</a>
|
||||
</p>
|
||||
It is **not** your normal Magic: The Gathering Cockatrice installation. Continuumatrice has an independent executable, application ID, Linux launcher, card database, deck directory, settings, cache, window branding, and URL scheme. It also supports Limbo, Refuge, and Oblivion as additional card piles.
|
||||
|
||||
---
|
||||
> **Status:** Active fork development. Features and packaging changes in draft pull requests are not released or validated until built and tested.
|
||||
|
||||
<br><pre><p align='center'>
|
||||
<b>To get started with Cockatrice ⇢ [view our webpage](https://cockatrice.github.io/)</b>
|
||||
<b>To get support, or suggest changes to the app ⇢ [file an issue](https://github.com/Cockatrice/Cockatrice/issues) ([How?](https://github.com/Cockatrice/Cockatrice/wiki/How-to-Create-a-GitHub-Ticket-Regarding-Cockatrice))</b><br>
|
||||
<b>To learn about the app and its code ⇢ [read our code documentation](https://cockatrice.github.io/docs/)</b>
|
||||
<b>To help with development ⇢ learn [how to contribute](#contribute)</b>
|
||||
</pre><p><br>
|
||||
## What's different
|
||||
|
||||
- Front, Support, Command battlefield bands with theme overrides
|
||||
- Limbo, Refuge, and Oblivion as real server-backed public piles
|
||||
- Independent profile: `~/.local/share/Continuumatrice` and `~/.cache/Continuumatrice` by default on Linux
|
||||
- Independent URL handler: `continuumatrice://` (does not claim `cockatrice://`)
|
||||
- Own app icon, name and install identity; regular Cockatrice remains untouched
|
||||
- No built-in Magic card import or Scryfall download list by default
|
||||
- Card data supplied by your own Cockatrice XML v4-compatible files and images; the XML schema is still inherited from Cockatrice
|
||||
- Matching fork client/server required for the three new pile-zone names
|
||||
|
||||
# Cockatrice
|
||||
**Game rules are not automatically enforced** by the generic tabletop client. These piles are functional card containers, not an implementation of Continuum Universes rules themselves.
|
||||
|
||||
Cockatrice is an open-source, multiplatform application for playing tabletop card games over a network. The program's server design prevents users from manipulating the game for unfair advantage. The client also provides a single-player mode, which allows users to brew while offline.<br><br>
|
||||
This project uses <kbd>C++</kbd> and the <kbd>Qt</kbd> libraries.<br>
|
||||
## Build on openSUSE Tumbleweed
|
||||
|
||||
Install development packages for Qt 6, Protobuf, a C++20 compiler, CMake and Ninja. Refer to [Linux installation notes](doc/continuumatrice-linux-install.md) for the dependency setup.
|
||||
|
||||
# Download [](https://tooomm.github.io/github-release-stats/?username=Cockatrice&repository=Cockatrice&search=0)
|
||||
|
||||
Downloads are available for **stable releases** and the current **beta version** in development.
|
||||
There is no strict release schedule for either of them.
|
||||
<br><pre>
|
||||
Latest <kbd>stable</kbd> release:
|
||||
[](https://github.com/cockatrice/cockatrice/releases/latest)  [](https://tooomm.github.io/github-release-stats/?username=Cockatrice&repository=Cockatrice&search=0)
|
||||
</pre><pre>
|
||||
Latest <kbd>beta</kbd> version:
|
||||
[](https://github.com/cockatrice/cockatrice/releases)  [](https://tooomm.github.io/github-release-stats/?username=Cockatrice&repository=Cockatrice&search=0) [](https://github.com/Cockatrice/Cockatrice/pulls?q=is%3Apr+is%3Aclosed)
|
||||
<sub><i>While incorporating the latest fixes and features, beta builds may not be stable or contain new bugs!</i></sub>
|
||||
<sub><b><i>Please report any findings and open new issues when testing them!</i></b></sub>
|
||||
</pre>
|
||||
|
||||
# Related Repositories
|
||||
|
||||
- [Magic-Token](https://github.com/Cockatrice/Magic-Token): File with MtG token data for use in Cockatrice
|
||||
- [Magic-Spoiler](https://github.com/Cockatrice/Magic-Spoiler): Code to generate MtG spoiler data from [MTGJSON](https://github.com/mtgjson/mtgjson) for use in Cockatrice
|
||||
- [cockatrice.github.io](https://github.com/Cockatrice/cockatrice.github.io): Code of the official Cockatrice webpage
|
||||
- [io.github.Cockatrice.cockatrice](https://github.com/flathub/io.github.Cockatrice.cockatrice): Configuration of our Linux `flatpak` package hosted at [Flathub](https://flathub.org/en/apps/io.github.Cockatrice.cockatrice)
|
||||
- [Webatrice](https://github.com/Cockatrice/Webatrice): Web client for Cockatrice servers (TypeScript / React)
|
||||
|
||||
|
||||
# Community Resources [](https://discord.gg/3Z9yzmA)
|
||||
|
||||
Join our [Discord community](https://discord.gg/3Z9yzmA) to connect with other project contributors (`#dev` channel) or fellow users of the app. Come here to talk about the application, features, or just to hang out.
|
||||
- [Official Website](https://cockatrice.github.io)
|
||||
- [Official Wiki](https://github.com/Cockatrice/Cockatrice/wiki)
|
||||
- [Official Discord](https://discord.gg/3Z9yzmA)
|
||||
- [reddit r/Cockatrice](https://reddit.com/r/cockatrice)
|
||||
|
||||
> [!IMPORTANT]
|
||||
> For support regarding specific servers, please contact that server's admin/mods and use their dedicated communication channels rather than contacting the team building the software.
|
||||
|
||||
|
||||
# Contribute
|
||||
<p>
|
||||
<a href="#code">Code</a> <b>|</b>
|
||||
<a href="#documentation-">Documentation</a> <b>|</b>
|
||||
<a href="#translation-">Translation</a>
|
||||
</p>
|
||||
|
||||
#### Repository Activity
|
||||
|
||||
|
||||
<details>
|
||||
<summary><b>Kudos to all our amazing contributors ❤️</b></summary>
|
||||
<br>
|
||||
<a href="https://github.com/Cockatrice/Cockatrice/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=Cockatrice/Cockatrice" />
|
||||
</a><br>
|
||||
<sub><i>Made with <a href="https://contrib.rocks">contrib.rocks</a></i></sub>
|
||||
</details>
|
||||
|
||||
### Code
|
||||
|
||||
To commit code to the project, please review our [Contribution Guidelines](https://github.com/Cockatrice/Cockatrice/blob/master/.github/CONTRIBUTING.md) first.<br>
|
||||
We maintain two tags for contributors to easier find issues to potentially work on:
|
||||
- [](https://github.com/Cockatrice/Cockatrice/issues?utf8=%E2%9C%93&q=is%3Aopen%20is%3Aissue%20label%3A%22Good%20first%20issue%22%20)<br>
|
||||
Issues tagged in this way provide a simple way to get started. They don't require much experience to be worked on.
|
||||
- [](https://github.com/Cockatrice/Cockatrice/issues?utf8=%E2%9C%93&q=is%3Aopen%20is%3Aissue%20label%3A%22Help%20Wanted%22%20)<br>
|
||||
This tag is used for issues that we are looking for somebody to pick up. Often this is for feature suggestions we support, but don't have the time to work on ourselves.
|
||||
|
||||
For both tags, we're willing to provide help to contributors in showing them where and how they can make changes, as well as code reviews for submitted changes.<br>
|
||||
We'll happily advice on how best to implement a feature, or we can show you where the codebase is doing something similar before you get too far along - put a note on an issue you want to discuss more on!
|
||||
|
||||
You can also have a look at our `Todo List` in our [Code Documentation](https://cockatrice.github.io/docs) or search the repo for [`\todo` comments](https://github.com/search?q=repo%3ACockatrice%2FCockatrice%20%5Ctodo&type=code).
|
||||
|
||||
### Documentation [](https://github.com/Cockatrice/Cockatrice/actions/workflows/documentation-build.yml?query=event%3Arelease+event%3Aworkflow_dispatch)
|
||||
|
||||
There are various places where useful information for different needs are maintained:
|
||||
- [Official Code Documentation](https://cockatrice.github.io/docs/)
|
||||
- [Official Wiki](https://github.com/Cockatrice/Cockatrice/wiki) `Community supported`
|
||||
- [Official Webpage](https://cockatrice.github.io/)
|
||||
- [Official README](https://github.com/Cockatrice/Cockatrice/blob/master/README.md) `This file`
|
||||
- [Official CONTRIBUTING](https://github.com/Cockatrice/Cockatrice/blob/master/.github/CONTRIBUTING.md)
|
||||
|
||||
Cockatrice tries to use the [Google Developer Documentation Style Guide](https://developers.google.com/style/) to ensure consistent documentation.
|
||||
We encourage everybody to improve the documentation by suggesting edits based on this guide.
|
||||
|
||||
### Translation [](https://explore.transifex.com/cockatrice/cockatrice/)
|
||||
|
||||
Cockatrice uses Transifex to manage translations. You can help us bring <kbd>Cockatrice</kbd> and <kbd>Oracle</kbd> to your language and just adjust single wordings right from within your browser by visiting our [Transifex project page](https://explore.transifex.com/cockatrice/cockatrice/). The [Webatrice](https://github.com/seavor/Webatrice) web client manages its own translations in its repo.<br>
|
||||
|
||||
Check out our [Translator FAQ](https://github.com/Cockatrice/Cockatrice/wiki/Translation-FAQ) for more information about getting involved, and join a group of hundreds of others!<br>
|
||||
|
||||
|
||||
# Build [](https://github.com/Cockatrice/Cockatrice/actions/workflows/desktop-build.yml?query=branch%3Amaster+event%3Apush) [](https://github.com/Cockatrice/Cockatrice/actions/workflows/docker-release.yml?query=branch%3Amaster+event%3Apush)
|
||||
|
||||
Dependencies: *(for minimum versions search our [CMake file](https://github.com/Cockatrice/Cockatrice/blob/master/CMakeLists.txt))*
|
||||
- [Qt](https://www.qt.io/developers/)
|
||||
- [protobuf](https://github.com/protocolbuffers/protobuf)
|
||||
- [CMake](https://www.cmake.org/)
|
||||
|
||||
Oracle can *optionally* use some packages to load compressed card files:
|
||||
- [xz](https://tukaani.org/xz/)
|
||||
- [zlib](https://www.zlib.net/)
|
||||
|
||||
<br>
|
||||
|
||||
**Basic compilation steps:**
|
||||
```bash
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
make
|
||||
git clone https://github.com/Continuum-Universes-Studio/Continuumatrice.git
|
||||
cd Continuumatrice
|
||||
|
||||
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
|
||||
-DWITH_CLIENT=ON -DWITH_SERVER=OFF -DWITH_ORACLE=OFF
|
||||
|
||||
cmake --build build --target continuumatrice --parallel 16
|
||||
./build/cockatrice/continuumatrice
|
||||
```
|
||||
|
||||
You can then
|
||||
- Create a Cockatrice installation inside the `release` folder:
|
||||
```bash
|
||||
make install
|
||||
```
|
||||
- Or make an installation package specific to your system:
|
||||
```bash
|
||||
make package
|
||||
```
|
||||
The `cockatrice` CMake target is a backwards-compatible **build alias**, not the generated executable. An old `build/cockatrice/cockatrice` binary may still exist if you compiled an earlier version: it is stale, not Continuumatrice.
|
||||
|
||||
> [!NOTE]
|
||||
> Detailed compiling instructions can be found in the Cockatrice wiki at [Compiling Cockatrice](https://github.com/Cockatrice/Cockatrice/wiki/Compiling-Cockatrice)
|
||||
To install under an appropriate prefix:
|
||||
|
||||
<br>
|
||||
```bash
|
||||
cmake --install build
|
||||
```
|
||||
|
||||
The following flags (with their non-default values) can be passed to `cmake`:
|
||||
| Flag | Description |
|
||||
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `-DWITH_SERVER=1` | Build <kbd>Servatrice</kbd> server |
|
||||
| `-DWITH_CLIENT=0` | Don't build <kbd>Cockatrice</kbd> client |
|
||||
| `-DWITH_ORACLE=0` | Don't build <kbd>Oracle</kbd> card database tool |
|
||||
| `-DCMAKE_BUILD_TYPE=Debug` | Compile in debug mode<br> Enables extra logging output, debug symbols, and much more verbose compiler warnings |
|
||||
| `-DWARNING_AS_ERROR=0` | Don't treat compilation warnings as errors in debug mode |
|
||||
| `-DUPDATE_TRANSLATIONS=1` | Configure `make` to update the translation .ts files for new strings in the source code<br> **Note:** `make clean` will remove the .ts files |
|
||||
| `-DTEST=1` | Enable regression tests<br> **Note:** `make test` to run tests, *googletest* will be downloaded if not available |
|
||||
Inspect `CMAKE_INSTALL_PREFIX` before installing, particularly on a machine that already has Cockatrice. The fork does not install or remove `/usr/bin/cockatrice` or the upstream `cockatrice.desktop`.
|
||||
|
||||
> [!TIP]
|
||||
> Build code documentation ([Doxygen](https://www.doxygen.nl)) according to our [configuration](https://github.com/Cockatrice/Cockatrice/blob/master/Doxyfile) into `/docs`:
|
||||
> ```bash
|
||||
> doxygen Doxyfile
|
||||
> ```
|
||||
## Card catalogue
|
||||
|
||||
The fork accepts XML version 4 for the time being. An empty `cards.xml` is created on a fresh profile; store your Continuum Universes sets in `~/.local/share/Continuumatrice/customsets/`, then reload the card database.
|
||||
|
||||
# Run
|
||||
Images live under `~/.local/share/Continuumatrice/pics/`. Custom graphics and themed pile icons are supported; no MTG catalogue is required.
|
||||
|
||||
<kbd>Cockatrice</kbd> is the game client<br>
|
||||
<kbd>Oracle</kbd> fetches card data<br>
|
||||
<kbd>Servatrice</kbd> is the server<br>
|
||||
- [Card XML and assets](doc/continuumatrice-card-data.md)
|
||||
- [Special piles and theme icons](doc/continuumatrice-special-piles.md)
|
||||
- [Battlefield bands](doc/continuumatrice-battlefield.md)
|
||||
- [Linux coexistence with Cockatrice](doc/continuumatrice-linux-install.md)
|
||||
|
||||
#### Docker
|
||||
## Independent product boundary
|
||||
|
||||
You can build an image & deploy a <kbd>Servatrice</kbd> (Cockatrice server) container using [Docker](https://www.docker.com/resources/what-container/) and our Dockerfile yourself.<br>
|
||||
The fork **must not** use upstream Cockatrice software-update releases, automatically import Magic card databases, register `.cod` as its own file type, or interfere with the original Cockatrice installation. A native Continuumatrice card importer and full multi-platform release validation are separate engineering work.
|
||||
|
||||
For more details, look into our wiki section on [Setting up Servatrice](https://github.com/Cockatrice/Cockatrice/wiki/Setting-up-Servatrice#using-docker).<br>
|
||||
You'll also find more hints on our **pre-build image** there, or the **docker-compose** file which will configure and run both a MySQL server and Servatrice.
|
||||
Legacy class names, the `cockatrice/` source directory, `libcockatrice_*` internal libraries, Protobuf protocol, and inherited card XML root element remain for source and wire compatibility; they do not represent the installed product name.
|
||||
|
||||
## License and upstream attribution
|
||||
|
||||
# License [](https://github.com/Cockatrice/Cockatrice/blob/master/LICENSE)
|
||||
Continuumatrice is derived from [Cockatrice](https://github.com/Cockatrice/Cockatrice), originally developed by the Cockatrice contributors. Existing copyright headers, contribution history and upstream license obligations are retained. See [LICENSE](LICENSE). The Continuumatrice modifications are maintained by Continuum Universes Studio.
|
||||
|
||||
Cockatrice is free software, licensed under the [GPLv2](https://github.com/Cockatrice/Cockatrice/blob/master/LICENSE).
|
||||
This is an independent fork, **not** an official Cockatrice release.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue