npm package: @raycenity/cge-core
Description: super simple, modular classic/ccg/rougelike card game engine
Author: jakobeha@fastmail.com
Latest version: 0.1.0

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

# CGE

Super simple framework to create classic, CCG, rougelike card games. Similar to and inspired by [boardgame.io](https://boardgame.io).

**WIP:** There is a package to automatically generate an AI using machine learning! Once you define the game rules and cards the AI will simulate your game to "learn" the best strategies. You can also feed it real match data and it will learn how to play like humans.

**[Code example](https://github.com/Jakobeha/cge-examples/src/readme.ts), [more code examples](https://github.com/Jakobeha/cge-examples)**

```shell
# Install pnpm on macOS or Linux: curl -fsSL https://get.pnpm.io/install.sh | sh -
# Install pnpm on Windows: iwr https://get.pnpm.io/install.ps1 -useb | iex
pnpm install @raycenity/cge-core
```

CGE is designed to be very modular. Game data and functions are separate, and player decisions are delegated to an "io" object. Rendering, input, networking, and AI are implemented outside CGE. CGE is very simple but there are related packages:

- **@raycenity/cge-network**: Websocket networking for CGE games (WIP)
- **@raycenity/cge-ai**: Machine Learing AI for CGE games (WIP)
- **@raycenity/cge-simple-example**: Simple CGE game example with line-by-line explanations
- **@raycenity/cge-project-example**: More complicated CGE game example using most of the features
- **@raycenity/cge-<foobar>-frontend**: Terminal and browser frontend for CGE games of limited form (WIP) using devolve-ui
- **@raycenity/devolve-ui**: Simple JSX-based UI using pixi.js with terminal preview

## CGE advantages

- Modular
- Strong types using the extreme power of TypeScript
- Separation of data, logic, and i/o (design patterns)
- 0 dependencies and small code size for the base package
- Premade extensions for AI (WIP), networking (WIP), and more (?)
- Documentation (WIP) and example projects (WIP) to help you get started

## Motivation

The card game is a *staple*: see classic card games like Poker and UNO (still played today), and modern games [Hearthstone], [Slay the Spire], as well as the millions of games they inspired.

Card game rules translate well into machine code. In theory, it should be very straightforward to implement a card game (unless it's too complex or unique). Straightforward enough that even people inexperienced with coding can create exciting, complex games.

Card games also have a lot in common with each other. Implementing them in a shared framework makes it easy to create machine learning models, alternate UIs / ports, mods, and other extensions.

As far as I'm aware there are not that many card game engines out there. And the ones that are out there are not really modular.

### Stretch goal: card games for everyone

Ultimately, CGE aims to make creating card games so easy it can become its own art form, and creatives who aren't even particularly experienced or determined can create card games, similar to RPGMaker spawning a lot of niche RPGs.

Even if CGE doesn't reach that goal, it's a really good framework to build card games on, with "good" design patterns and AI/networking/partial rendering from the start.

### Machine Learning enables new ranking and "games"

Machine learning in particular enables super balancing, ELO / prediction, and interesting gameplay mechanics.

In chess, every board configuration has a "probability" and a machine can play significantly better than any human. In Go, ML has discovered new moves and reshaped the metagame.

"Super balancing": since a strong ML model can accurately guess the "chance" of a particular deck winning, ML allows developers to balance their game and discover overpowered cards without having to wait for real-world user gameplay.

ML can also reduce luck, e.g. by ensuring that both players start with a hand that gives approximately the mean or median "predicted" chance of winning (i.e. 50/50 if they both have the same deck). Even if the game stays the same, ML can rate players solely based on how good they could've played their cards without luck (e.g. by comparing whether they won or lost to their win prediction, or just determining if they could've won had they played their cards better).

Lastly, ML can create games of its own. For example, see a card and guess the most "balanced" cost or effect. Since ML provides a source of truth on how the game is balanced, it can test how well players can balance the game themselves.

## Installing

CGE can be installed using [npm](https://www.npmjs.com/) or [pnpm](https://pnpm.io/).

```shell
pnpm install @raycenity/cge-core
```

CGE also exists as a [deno](https://deno.land) module *very soon*:

```typescript
import { Game, etc } from "https://deno.land/@raycenity/cge-core@X.Y.Z";
```

Alternatively you can just download the built code directly [here](https://github.com/Jakobeha/cge-core/releases/latest). The code is an unminified ES module (learn about ES modules [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules))

## High-level API

See [documentation](./docs) for more details.

TODO

## Repository info (e.g. for contributing)

CGE is built using [esbuild](https://esbuild.org/). The package manager used is [pnpm](https://pnpm.io/). Linting is done by [standard](https://standardjs.com/), however we use a *slightly* modified version removing some warnings which is run through `pnpm run lint` (specifically `node ts-standardx.mjs`).

Feel free to submit issues or pull requests. Also contribute to the documentation and notify if anything is unclear!