Lesson 8: Utility AI

Fight and flee only make sense while the enemy is within DANGER_RANGE, so score them inside if danger > 0: and leave them None otherwise. If a braver critter flees sooner, some consideration went negative: wrap it in clamp01(). If curiosity feels far too strong, check that no scoring function reads a trait.

The lab file has a few extra lines marked lab runtime near the top and and frame_budget() in the loop, so the instructor's checker can run it automatically. They do nothing when you run it yourself, and they are left out here.

"""Utility Critter: Advanced Lesson 8 practice exercise (solution).

A critter scores eat / fight / flee / explore every frame and does the best
one. F drops food, E drops an enemy, A/Z change aggression, C/X change caution,
H toggles hysteresis, SPACE pauses. The bars on the right are the live scores.
Close the window to quit.
"""
import math
import random

import pygame


PLAY_W, HEIGHT, PANEL_W = 700, 480, 300
SPEED = 120.0              # px/s
FLEE_SPEED = 150.0         # px/s
DANGER_RANGE = 300.0       # px: enemies farther than this are no threat
HYSTERESIS = 0.1           # the current action's bonus: a rival must win by more
ACTIONS = ["eat", "fight", "flee", "explore"]
TRAIT_OF = {"eat": None, "fight": "aggression", "flee": "caution", "explore": "curiosity"}
BAR_COLORS = {"eat": (250, 204, 21), "fight": (239, 68, 68), "flee": (249, 115, 22), "explore": (168, 85, 247)}


# ---------------------------------------------------------------- response curves
def clamp01(x):
    return max(0.0, min(1.0, x))


def linear(x):
    return clamp01(x)


def exponential(x, power=3):
    return clamp01(x) ** power


def sigmoid(x, k=10, center=0.5):
    return 1 / (1 + math.exp(-k * (clamp01(x) - center)))


def closeness(distance, max_range):
    """1.0 when touching, 0.0 at max_range or farther."""
    return 1 - clamp01(distance / max_range)


# ---------------------------------------------------------------- scoring
def base_scores(agent, world):
    """Each action's score in [0, 1], or None when its requirement fails.

    Considerations are multiplied, and every one is clamped to [0, 1] first,
    so a score can never go negative (a negative score would flip the meaning
    of every multiplier applied to it).
    """
    scores = {name: None for name in ACTIONS}
    food = nearest(agent["pos"], world["food"])
    enemy = nearest(agent["pos"], world["enemies"])
    if food is not None:
        near_food = 0.5 + 0.5 * closeness(agent["pos"].distance_to(food), 600)
        scores["eat"] = exponential(agent["hunger"]) * near_food
    if enemy is not None:
        danger = closeness(agent["pos"].distance_to(enemy["pos"]), DANGER_RANGE)
        if danger > 0:
            odds = clamp01(1 - 0.5 * enemy["strength"])   # stronger enemy, worse odds
            scores["fight"] = sigmoid(agent["health"]) * odds * clamp01(danger * 2)
            scores["flee"] = linear(1 - agent["health"])
    scores["explore"] = 0.6 * linear(agent["boredom"])
    return scores


def personality_multiplier(agent, action):
    """Trait 0..1 becomes a multiplier 0.5..1.5 (a trait of 0.5 is neutral). Applied ONCE."""
    trait = TRAIT_OF[action]
    return 1.0 if trait is None else 0.5 + clamp01(agent["traits"][trait])


def decide(agent, world, current=None, hysteresis=HYSTERESIS):
    """Return (best_action, final_scores). The current action gets a small bonus."""
    finals = {}
    for name, base in base_scores(agent, world).items():
        if base is None:
            finals[name] = None
            continue
        finals[name] = base * personality_multiplier(agent, name)
    best, best_value = "explore", -1.0
    for name, score in finals.items():
        if score is None:
            continue
        value = score + (hysteresis if name == current else 0.0)
        if value > best_value:
            best, best_value = name, value
    return best, finals


# ---------------------------------------------------------------- world
def nearest(pos, things):
    if not things:
        return None
    key = (lambda t: pos.distance_to(t)) if isinstance(things[0], pygame.Vector2) else \
          (lambda t: pos.distance_to(t["pos"]))
    return min(things, key=key)


def new_agent():
    return {"pos": pygame.Vector2(PLAY_W / 2, HEIGHT / 2), "hunger": 0.3, "health": 1.0, "boredom": 0.5,
            "traits": {"aggression": 0.5, "caution": 0.5, "curiosity": 0.5},
            "wander": pygame.Vector2(PLAY_W / 2, HEIGHT / 2)}


def move_toward(agent, target, speed, dt):
    offset = target - agent["pos"]
    agent["pos"] += offset.clamp_magnitude(speed * dt)
    return offset.length()


def act(agent, world, action, dt, rng):
    """Carry out one frame of the chosen action, then let the needs drift."""
    if action == "eat":
        food = nearest(agent["pos"], world["food"])
        if food is not None and move_toward(agent, food, SPEED, dt) < 8:
            world["food"].remove(food)
            agent["hunger"] = 0.0
    elif action == "fight":
        enemy = nearest(agent["pos"], world["enemies"])
        if enemy is not None and move_toward(agent, enemy["pos"], SPEED, dt) < 22:
            enemy["hp"] -= 0.35 * dt
            agent["health"] -= 0.3 * enemy["strength"] * dt
            if enemy["hp"] <= 0:
                world["enemies"].remove(enemy)
    elif action == "flee":
        enemy = nearest(agent["pos"], world["enemies"])
        if enemy is not None:
            away = agent["pos"] - enemy["pos"]
            if away.length_squared() == 0:
                away = pygame.Vector2(1, 0)
            agent["pos"] += away.normalize() * FLEE_SPEED * dt
    else:
        if move_toward(agent, agent["wander"], SPEED * 0.6, dt) < 8:
            agent["wander"] = pygame.Vector2(rng.uniform(30, PLAY_W - 30), rng.uniform(30, HEIGHT - 30))
        agent["boredom"] -= 0.25 * dt
    agent["hunger"] = clamp01(agent["hunger"] + 0.04 * dt)
    if action != "explore":
        agent["boredom"] += 0.05 * dt
    agent["boredom"] = clamp01(agent["boredom"])
    enemy = nearest(agent["pos"], world["enemies"])
    if enemy is None or agent["pos"].distance_to(enemy["pos"]) >= DANGER_RANGE:
        agent["health"] += 0.05 * dt           # only heals when no enemy is in range
    agent["health"] = clamp01(agent["health"])
    agent["pos"].x = max(10, min(PLAY_W - 10, agent["pos"].x))
    agent["pos"].y = max(10, min(HEIGHT - 10, agent["pos"].y))


def draw_panel(surface, font, agent, finals, action, hysteresis_on, switches):
    x0 = PLAY_W + 12
    pygame.draw.rect(surface, (15, 23, 42), (PLAY_W, 0, PANEL_W, HEIGHT))
    surface.blit(font.render("Scores (after personality)", True, (203, 213, 225)), (x0, 12))
    for i, name in enumerate(ACTIONS):
        y = 44 + i * 40
        score = finals[name]
        surface.blit(font.render(name, True, (226, 232, 240)), (x0, y))
        if score is None:
            surface.blit(font.render("not possible", True, (100, 116, 139)), (x0 + 70, y))
            continue
        color = BAR_COLORS[name] if name == action else tuple(c // 2 for c in BAR_COLORS[name])
        pygame.draw.rect(surface, color, (x0 + 70, y, max(2, int(140 * score)), 18))
        surface.blit(font.render(f"{score:.2f}", True, (226, 232, 240)), (x0 + 220, y))
    lines = [f"doing: {action}",
             f"hunger {agent['hunger']:.2f}  health {agent['health']:.2f}",
             f"boredom {agent['boredom']:.2f}",
             f"aggression {agent['traits']['aggression']:.1f}  caution {agent['traits']['caution']:.1f}",
             f"hysteresis {'ON' if hysteresis_on else 'off'}   switches {switches}",
             "F food  E enemy  A/Z  C/X  H  SPACE"]
    for i, text in enumerate(lines):
        surface.blit(font.render(text, True, (203, 213, 225)), (x0, 230 + i * 26))


def main():
    pygame.init()
    screen = pygame.display.set_mode((PLAY_W + PANEL_W, HEIGHT))
    pygame.display.set_caption("Utility Critter")
    clock = pygame.time.Clock()
    font = pygame.font.Font(None, 22)
    rng = random.Random(11)

    agent = new_agent()
    world = {"food": [], "enemies": []}
    action, switches = "explore", 0
    hysteresis_on, paused = True, False

    running = True
    while running:
        dt = min(clock.tick(60) / 1000, 0.05)
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                running = False
            elif event.type == pygame.KEYDOWN:
                traits = agent["traits"]
                if event.key == pygame.K_f:
                    world["food"].append(pygame.Vector2(rng.uniform(30, PLAY_W - 30), rng.uniform(30, HEIGHT - 30)))
                elif event.key == pygame.K_e:
                    spot = agent["pos"] + pygame.Vector2(160, 0).rotate(rng.uniform(0, 360))
                    spot.x = max(20, min(PLAY_W - 20, spot.x))
                    spot.y = max(20, min(HEIGHT - 20, spot.y))
                    world["enemies"].append({"pos": spot, "hp": 1.2, "strength": 0.5})
                elif event.key in (pygame.K_a, pygame.K_z):
                    step = 0.1 if event.key == pygame.K_a else -0.1
                    traits["aggression"] = round(clamp01(traits["aggression"] + step), 1)
                elif event.key in (pygame.K_c, pygame.K_x):
                    step = 0.1 if event.key == pygame.K_c else -0.1
                    traits["caution"] = round(clamp01(traits["caution"] + step), 1)
                elif event.key == pygame.K_h:
                    hysteresis_on = not hysteresis_on
                elif event.key == pygame.K_SPACE:
                    paused = not paused

        choice, finals = decide(agent, world, action, HYSTERESIS if hysteresis_on else 0.0)
        if not paused:
            if choice != action:
                switches += 1
                action = choice
            act(agent, world, action, dt, rng)

        screen.fill((30, 41, 59))
        for food in world["food"]:
            pygame.draw.circle(screen, (250, 204, 21), food, 7)
        for enemy in world["enemies"]:
            pygame.draw.circle(screen, (70, 40, 40), enemy["pos"], DANGER_RANGE, 1)
            pygame.draw.circle(screen, (239, 68, 68), enemy["pos"], 11)
        pygame.draw.circle(screen, (96, 165, 250), agent["pos"], 12)
        draw_panel(screen, font, agent, finals, action, hysteresis_on, switches)
        pygame.display.flip()

    pygame.quit()
    print(f"final action: {action}; switches: {switches}; hysteresis {'on' if hysteresis_on else 'off'}")
    print(f"aggression {agent['traits']['aggression']:.1f}, health {agent['health']:.2f}")


if __name__ == "__main__":
    main()