Enemies — beetles

Draft

No enemy code exists yet. The vendored Hello Mario Framework ships a full enemy set (Assets/HelloMarioFramework/Script/Enemy) which is not being used — beetles are their own thing and will be written against the hose rather than against stomping. Beetles are wave 2.

What they are

Protagonist-sized beetles. Beautiful, not gross — iridescent shells, deliberate movements, the kind of insect you would stop and look at if it were the size of your thumb instead of the size of you. They are not vermin and they are not soldiers. They live on the mountain and the mountain is what you are trying to cross.

Design intent: the player's first reaction to a beetle should be interest, and the second should be to back away slowly. Everything about their behaviour is built to make the fight optional and the aggression earned.

Behaviour

Calm

Roaming, unhurried, on their own business. They do not path towards the player and they do not patrol a route — they wander a home area. A player who moves through quietly and does not spray gets past without a fight. This is the intended default outcome for most beetles.

Alert

A beetle goes alert when either:

• It sees the player — inside a forward vision cone at range, unobstructed; or
• It notices another beetle noticed the player. This is the important one. Alertness propagates. A single beetle spotting you turns a slope into a problem, which is what makes approach and cover matter on the trail.

Second-hand alerting should have a shorter reach than direct sight, so a cluster wakes up in a visible ripple rather than all at once.

Reaction

On going alert, a beetle turns to face the player and performs a wing display — the elytra open and the wings flap, a threat display, loud and large. This is the game telling you clearly: back off now and this does not happen.

The display has a duration. During it the beetle does not attack. That window is the player's whole opportunity to retreat, break line of sight, or commit.

Swoop attack

Provoked if the player, during or after the display, either:

• gets too close, or
• sprays the beetle.

The beetle takes off and swoops. A hit knocks the player down the mountain — loss of altitude, not loss of health. This is the correct punishment for the game: it costs the tank water and the time it takes to re-climb, and it never sends you to a menu.

The knockback should be substantial enough that a beetle fight above a long drop is genuinely expensive, and the recovery should always be possible with a full tank.

State machine

stateDiagram-v2
    [*] --> Calm

    Calm --> Alert: sees player
    Calm --> Alert: notices a nearby beetle went alert

    Alert --> Reaction: turn to face player

    Reaction --> Display: wing display / flap

    Display --> Swoop: player too close
    Display --> Swoop: player sprays beetle
    Display --> Alert: display duration elapses,<br/>player still visible
    Display --> Calm: player lost / left the area

    Swoop --> Recover: knocks player down the mountain
    Recover --> Alert: player still visible
    Recover --> Calm: player gone

    Alert --> Calm: player lost for N seconds

Open questions

• Can beetles be killed? Preference is no, or not with water alone. A beetle that can be hosed off a ledge is a beetle the player will farm. Knocking one off its perch is more interesting than killing it.
• Does spraying do anything useful at all? Options: stagger, cancel a swoop mid-air, or wash them off a wall. Something must reward the trigger or the encounter has no verb.
• Alert propagation shape. Radius, or line of sight between beetles? Line of sight is more readable and more expensive.
• Do they respawn? If knockdown is the only cost, respawning is fine and probably good.