cromulant/README.md

113 lines
3.4 KiB
Markdown
Raw Normal View History

2024-07-20 11:24:24 +00:00
# Cromulant
2024-07-22 07:26:29 +00:00
[Click here for screenshots](screenshots.md)
2024-07-22 07:25:06 +00:00
2024-07-20 11:24:24 +00:00
## What is this?
2024-07-20 11:16:02 +00:00
This is a kind of toy you can use for your amusement.
2024-07-28 09:53:49 +00:00
It requires minimal interaction, most things happen automatically.
2024-07-20 11:16:02 +00:00
2024-07-28 10:11:22 +00:00
You might want to keep it running in some tiled layout.
2024-07-20 11:16:02 +00:00
2024-07-28 09:52:20 +00:00
## Usage
2024-07-20 11:16:02 +00:00
2024-07-28 09:52:20 +00:00
You start with a set of `25` to `250` random ants (`100` by default).
2024-07-21 07:25:48 +00:00
2024-07-28 09:52:20 +00:00
You can specify this anytime through `Restart`. When you restart everything resets to zero like triumphs and hits.
2024-07-20 11:16:02 +00:00
2024-07-28 09:52:20 +00:00
There are `1000` names available. This is used as the pool of names to select randomly.
Every x minutes or seconds a new update from a random ant appears.
The content of the update depends on a random number.
It can be a triumph, a hit, travel, thought, sentence.
2024-07-20 11:16:02 +00:00
The ant with the highest score is shown in the footer.
2024-07-21 07:18:23 +00:00
Ants get merged and replaced over time.
2024-07-21 06:27:44 +00:00
2024-07-28 09:52:20 +00:00
All of this happens automatically, though you can manually force actions
by using the mouse on the portraits or main menu. Try click and middle click.
2024-07-21 10:21:01 +00:00
2024-07-28 09:52:20 +00:00
Read [Algorithm](#algorithm) for more information about the mechanics.
2024-07-21 13:44:00 +00:00
2024-07-20 15:31:01 +00:00
## Installation
2024-07-28 09:41:47 +00:00
### Quick Installation
If you have `pipx` and `linux` installed you can use the following command:
2024-07-20 15:31:01 +00:00
```sh
pipx install git+https://github.com/madprops/cromulant --force
```
2024-07-28 09:41:47 +00:00
### Advanced Installation
1) Clone this repo.
2) python -m venv venv
3) venv/bin/pip install -r requirements.txt
4) Use `run.sh` or `venv/bin/python -m cromulant.main`
5) (Optional) Manually create desktop entries and icons for the application.
2024-07-28 10:04:00 +00:00
### Limitations
Since it's python you will need to remake the virtual env if you rename/move the directory.
And the environment might simply not work after python upgrades, requiring you to remake the virtual env or re-install through pipx.
2024-07-28 09:52:20 +00:00
## Algorithm <a name="algorithm"></a>
2024-07-20 11:16:02 +00:00
2024-07-20 12:55:15 +00:00
A random ant is picked based on weights (oldest update date weighs more).
2024-07-28 10:05:28 +00:00
More weight means something is more likely to get picked.
2024-07-28 09:56:51 +00:00
Then a random number between 0 and length-of-methods-1 is picked.
2024-07-20 11:22:21 +00:00
For each number an action happens to produce an update.
2024-07-28 10:10:10 +00:00
Words (sentences) have more weight compared to the rest of the update methods.
Some methods roll another number to pick the outcome like in the case of `think`
where there are 3 `think` types, these can also have custom weights.
The top score is calculated on every new update.
The score is calculated as (`Triumph` - `Hits`).
2024-07-22 04:05:17 +00:00
If multiple ants have the same score, the oldest one wins.
2024-07-28 10:10:10 +00:00
The ant with the top score is shown in the footer.
The top ant uses a special portrait on updates.
2024-07-20 15:26:40 +00:00
2024-07-21 06:55:37 +00:00
For merge, the words of each name are used.
They get filled with random words if less than 2 words.
One word from each set is picked randomly.
The triumph and hits get combined.
The original ants get terminated and the merged one hatches.
2024-07-21 07:28:06 +00:00
An extra random ant is hatched to fill the gap.
2024-07-21 06:55:37 +00:00
2024-07-28 10:00:09 +00:00
## Storage
The state of ants is stored in `~/.local/share/cromulant/ants.json`
The settings file is stored in `~/.config/cromulant/settings.json`
Or the equivalents in non-linux systems.
2024-07-20 11:26:29 +00:00
## Technology
This is made with python + qt (pyside6)
2024-07-20 11:47:50 +00:00
## The name
2024-07-27 05:41:31 +00:00
I read the word [cromulent](https://www.merriam-webster.com/wordplay/what-does-cromulent-mean) being used somewhere which turned out to be invented by The Simpsons.
2024-07-20 11:47:50 +00:00
2024-07-20 11:50:53 +00:00
I created a new programming project to practice/study and tried to use that word for the name but made a typo.
2024-07-20 11:47:50 +00:00
2024-07-28 10:17:33 +00:00
I liked the typo and made a game around it.
2024-07-20 11:47:50 +00:00
2024-07-22 07:29:03 +00:00
---
2024-07-20 11:22:21 +00:00
2024-07-27 03:57:19 +00:00
[Command line arguments](arguments.md)
2024-07-22 07:29:03 +00:00
[Click here for more](more.md)