> For the complete documentation index, see [llms.txt](https://docs.spoof.dev/asteroid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spoof.dev/asteroid/getting-started/how-asteroid-works.md).

# How Asteroid Works

This page explains the ideas behind Asteroid. Once you understand these, every setting in the config makes sense.

## Fake players

A fake player is a real server-side player entity that has no human behind it. To the server, and to other plugins, it looks and behaves like a normal player. It has a name, a skin, a UUID, an inventory, ping, and a position in the world.

Because it is a genuine player entity, it counts toward the player total, appears in `/list` and the tab list, and can be targeted by other plugins (economy, ranks, auctions, and so on).

## Profiles

A **profile** is the identity a fake player wears: a username and a skin. Profiles are generated ahead of time and stored in your database. When Asteroid needs to spawn a fake player, it picks an unused profile from the pool. When the fake player leaves, the profile returns to the pool and can be reused later.

## The spoofing loop

While spoofing is enabled (`/asteroid toggle`), Asteroid runs a loop that keeps the number of fake players close to a target. Every cycle it asks one question: do we have too few fake players, the right amount, or too many?

* **Too few:** it spawns a new fake player using an unused profile, after the join delay.
* **Too many:** it disconnects a fake player, after the disconnect delay.
* **Just right:** it does nothing and waits.

The target number is worked out from your `min`, `max`, and `multiplier` settings, plus the number of real players online.

## Fluctuation

A fixed target would look robotic. **Fluctuation** changes the target over time so the fake count rises and falls naturally, based on real activity, the time of day, or even machine-learning predictions from your server's own history.

## Lifespan and staggering

Each fake player has a **lifespan**: how long it stays online before it disconnects on its own. Lifespans are randomized so players do not all leave at once. Joins and disconnects are also **staggered** with delays, so you never see a wave of players appear or vanish in the same second.

## What fake players do while online

Beyond just existing, fake players can be given behavior:

* **On-join commands** run the moment a fake player joins.
* **The scheduler** runs actions at random intervals while they are online.
* **Movement** makes them walk, jump, swim, climb, and destroy blocks.
* **AI** lets them reply to real players in chat.
* **Addons** add extra behavior like voting, ranks, and ping changes.

## Multi-server networks

If you run several servers behind BungeeCord or Velocity, Asteroid can sync fake players across the whole network, so they show up in the proxy's global player list and network-wide placeholders. This uses a shared backend (Redis, Lettuce, or MySQL) so all servers agree on who is online.

## Two building blocks you will reuse everywhere

### Random numbers

`{random[x,y]}` picks a random whole number between x and y. Example: `{random[5,20]}` might give 5, 12, or 20. `{random[x,y,z]}` is the same but only multiples of z, so `{random[100,1000,50]}` gives 100, 150, up to 1000.

### Weighted selection

Many lists pick one entry using **weights**. A weight is a relative number, not a percentage. Higher weight means more likely. With weights 100, 80, and 60 (total 240), the first is picked about 42 percent of the time, the second about 33 percent, and the third about 25 percent.