Ligar

Três operadores põem um valor num campo. = copia o valor de agora. @= liga o campo a uma fórmula: o Scena refaz a conta sempre que algo que ela lê muda. << copia os valores de outro objeto para dentro deste, sem trocar o objeto. O @= vai sempre com colchetes do lado esquerdo — c["radius"] @= lambda: … — porque c.radius já seria o número, não o campo.

st.score = 0
st.lives = 3
st["hud"] @= lambda: f"Stars {st.score}"          # @= cria o campo se faltar

c.radius = 10
c.radius = other.radius
c["radius"] @= lambda: player.hp * 10
hero["grounded"] @= lambda: "bottom" in hero.touching_sides
line["p1"] @= lambda: rect.top_left
turret["angle"] @= lambda: dial.value
ship["scale"] @= lambda: 1 + 0.2 * st.pulse

# mouse inteiro é um ponto (link direto). .x / keyp ainda precisam de lambda — ver Frame
cursor["center"] @= mouse
c.center["x"] @= lambda: 1200 if keyp("D") else 800

# cópia agora
Circle(center=player.center, radius=player.hp)
# liga ao vivo
Circle(center=lambda: player.center, radius=lambda: player.hp * 10)

# << : substitui o conteúdo; o objeto da esquerda continua o mesmo
pos = Vec2(0, 0)
pos << Vec2(50, 50)          # mesmo pos; valores novos
c.center << other.center     # other continua no jogo
# c.absorb(other)            # isso sim some com other

c["radius"].unlink()
c.unlink_all()

Não confundir

O que pode ser ligado

Do lado esquerdo do @= fica o campo que vai mudar; do direito, a fórmula — em geral um lambda:. A fórmula precisa ler pelo menos uma coisa que o Scena acompanha (um campo, um objeto, st, clock, keyp, mouse): é assim que ele sabe quando refazer a conta.

A direita precisa nomear algo que o Scena acompanha. Variável Python comum não avisa quando muda: o @= recusa com TypeError.

O que é reativo (pode aparecer na direita e puxar atualização):

• Point, Vec2, Shape (Circle, Rect, Line, …), Sprite, Entity — e os campos deles (c.radius, ship.center, hero.hp…)
• st (e qualquer State) — st.score, st.lives…
• clock, keyp, mouse — entrada do frame (sempre dentro de lambda:)
• mic.level, audio.level, h.level (de um play_sound) e os .spectrum() deles — medidas do som, atualizadas uma vez por frame (Microphone)
• Campo solto: Attribute(0.0)

Campos que você cria numa Entity já entram nesse mundo sozinhos — Guardar valores.

Formas canônicas

As duas grafias de todos os dias. A expressão à direita devolve algo compatível com o alvo, e nomeia pelo menos um objeto reativo:

# objeto["campo"] @= lambda: expressão compatível com o campo
dst["xyz"] @= lambda: src.abc

# Point: um lambda que devolve o par
circle1["center"] @= lambda: (a.x * 2 + 10, b.abc / 2)
# par de lambdas (um por eixo) — grafia do construtor:
# Circle(center=(lambda: a.x * 2 + 10, lambda: b.abc / 2))

A regra geral, no dia a dia:

objeto["campo"] @= lambda: obj1.campo_a + obj2.campo_b

Exemplos concretos:

c["radius"] @= lambda: ship.hp * 0.1
hud["text"] @= lambda: f"Wave {st.wave}"
cursor["center"] @= mouse
twin["angle"] @= (lambda h=host: h.angle)

Num for, cada lambda precisa do seu objeto: lambda h=host: h.angle — ver Lambda.

Dentro da fórmula, ponto. A lambda já mantém a conta viva: o Scena lê st.score no código e refaz a conta quando a célula muda. Colchetes dentro dela (lambda: st["score"] * 2, f"{st['score']}", c["radius"]) dariam a célula, não o número: o @= (e a lambda de um construtor) recusa com TypeError, apontando a linha e a grafia com ponto. Um colchete sozinho à direita, sem lambda, é a ligação direta: c["radius"] @= st["raio"].

Formas mais curtas, também legais

Funcionam, mas não são o caminho sugerido. Sem lambda, os dois lados precisam já ser objetos que o Scena acompanha (um campo, um Point, um Vec2) — o Python não calcula a expressão antes:

objeto1 @= src                 # se objeto1 e src forem objetos do Scena (Point, Vec2, campo)
dst["xyz"] @= src["abc"]       # se xyz e abc forem campos reativos
line["p1"] @= rect.top_left    # liga direto ao Point da direita, sem conta
orbit.center @= earth.center

Número ou conta já resolvida (host.angle, player.hp * 10) vira float antes do @= ver — TypeError. Use lambda:.

Função com nome

Quando a conta tem vários casos, escreva um def e ligue a função (sem parênteses). O Scena lê o código da função, uma vez, para saber do que ela depende — igual ao lambda:

def texto_placar():
    if st.venceu:
        return "Você venceu!"
    if st.morto:
        return f"Fim de jogo — estrelas {st.estrelas}"
    return f"Estrelas {st.estrelas}   Vidas {st.vidas}"

placar["text"] @= texto_placar       # sem () — liga a função, não o resultado
placar["text"] @= lambda: texto_placar()   # também vale: o Scena segue a função

Também vale já no construtor: Text(texto_placar, top_left=(20, 580)) faz a mesma ligação.

Pode usar if, variáveis locais, len / min / round, math, funções do Scena e outras funções do mesmo arquivo (até 3 níveis). O Scena recusa com TypeError o que ele não consegue enxergar lendo o código — senão a ligação ficaria parada sem avisar:

• for / while / [… for … in …] — os itens só existem quando roda. Faça no update().
• Ler um grupo (len(group["inimigo"])) — use update() ou uma fórmula de grupo.
• Mudar um objeto do Scena dentro da fórmula (c.radius = 5) — a fórmula só lê e devolve.
• Índice que muda numa lista de objetos (bolas[st.i].radius) — nomeie o objeto.
• Chamar função de outro arquivo, getattr / eval, def ou lambda dentro da fórmula, try.

Não funciona — variável Python comum não avisa o Scena quando muda; número cru também não:

x = 10
c["radius"] @= lambda: x * 2  # TypeError: a fórmula não nomeia nada reativo

# também TypeError — host.angle já virou float
# twin["angle"] @= host.angle

# certo: colchetes no campo, ou lambda que nomeia o Shape
twin["angle"] @= host["angle"]
twin["angle"] @= lambda: host.angle

# certo: colocar em st (ou Attribute) e nomear isso
st.x = 10
c["radius"] @= lambda: st.x * 2

Dá para criar um valor reativo à mão, sem Shape:

from scena import Attribute, State

pulse = Attribute(0.0)           # um campo solto, fora de qualquer objeto
hud = State(name="hud")          # outro conjunto de campos, como o st
hud.level = 0

ring["scale"] @= lambda: 1 + pulse
label["text"] @= lambda: f"{hud.level}"

Não confundir

Lambda

lambda: guarda a conta para o Scena refazer depois. Num for, prenda o objeto: lambda b=bola: b.center.

Sem lambda, o Python calcula na hora e o Scena recebe um número. Com lambda:, o Scena guarda a conta e refaz quando a fonte muda:

c["radius"] @= lambda: player.hp * 10
cursor["center"] @= lambda: mouse

O lambda olha o nome na hora de atualizar, não na hora em que você escreveu a linha. Num for, o nome bola vai de um círculo para o próximo. No fim, todos os lambdas veem o último — e todas as linhas seguem ele.

# errado — as 20 linhas seguem a última bola
for i in range(20):
    bola = Circle(center=canvas.game_view.center, radius=16)
    Line(p1=(50, 50), p2=lambda: bola.center)

# certo — b=bola guarda esta bola agora
for i in range(20):
    bola = Circle(center=canvas.game_view.center, radius=16)
    Line(p1=(50, 50), p2=lambda b=bola: b.center)

No corpo use b.center, não bola.center. O centro continua ao vivo; só fica fixo qual bola. Se o nome nunca muda (um ponto1 criado uma vez), lambda: ponto1 basta — todos devem seguir o mesmo ponto.

Callback que escreve um atributo (after, on_done, …): lambda só aceita expressão — atribuição com = não entra. Use setattr:

# errado — SyntaxError (lambda não aceita atribuição)
# after(1.0, lambda: player.active = True)

after(1.0, lambda: setattr(player, "active", True))
ship.dissolve_out(0.4, on_done=lambda: setattr(ship, "active", False))

Se quiser a grafia player.active = True

def wake():
    player.active = True
after(1.0, wake)

Fórmulas nos construtores

Um objeto também pode nascer ligado: passe lambda: em vez de um valor e o parâmetro passa a seguir a fórmula, como um @= feito logo depois. Um valor sem lambda é copiado uma vez. Só os parâmetros de geometria (posição, tamanho, ângulo) aceitam lambda — não cor, camada ou tag.

Sem lambda, o Python calcula na hora e o objeto nasce com aquele número / ponto. Com lambda:, o Scena guarda a conta e refaz quando a fonte muda — o mesmo que um @= depois:

# cópia agora — player pode andar; este Circle fica onde nasceu
Circle(center=player.center, radius=player.hp)

# liga ao vivo — acompanha o jogador e o HP
Circle(center=lambda: player.center, radius=lambda: player.hp * 10)

Um ponto aceita um lambda que devolve o par, ou um par de lambdas (um por eixo). O par é grafia do construtor; depois da criação use c["center"] @= lambda: (…, …) ou ligue cada eixo.

Circle(center=lambda: player.center)
Circle(center=(lambda: a.x * 2 + 10, lambda: b.abc / 2))
p = Point(0, 300)
p["x"] @= lambda: mouse.x                 # um eixo ligado, o outro copiado
Line(p1=(50, 50), p2=lambda: bola.center)

A regra é a mesma em todo construtor de geometria: callable → liga; resto → copia. Um ponto sem lambda (center=player.center) copia — não acompanha. Para acompanhar, use lambda: (ou @= depois).

Não confundir

Guardar valores: st e campos da Entity

Dois lugares para os seus valores: st, para os valores do jogo como um todo (placar, vidas, onda, opções), e campos na própria Entity, para o que é dela (HP, grounded, munição). Nos dois, o campo nasce na primeira gravação (st.score = 0, ship.hp = 3) e já é acompanhado pelo Scena: fórmulas @=, @when e widgets podem ler dele.

Sprite, Circle, Rect, Line, Text, SpatialFx — e o Entity() sem desenho — são Entity. Geometria já existe (center, radius, width…); o que você inventa é campo próprio. Placar, onda, flag do app: st. HP, grounded, munição: na Entity que os possui.

O campo próprio (hp, grounded, wave) vira um Attribute na primeira gravação. A partir daí o Scena acompanha o campo: widgets, @=, @when e @on_change podem ler dele.

st.score = 0                  # cria o campo
st.lives = 3
st["hud"] @= lambda: f"Stars {st.score}"   # @= cria o campo se faltar

ship = Sprite("nave.png")     # Sprite é Entity
c = Circle()                  # Circle também
diretor = Entity()            # sem desenho, mesmos campos

ship.hp = 100                 # cria o campo — já acompanhado
c["radius"] @= lambda: ship.hp * 10

# @= no colchete também cria, se o nome ainda não existe
hero["grounded"] @= lambda: "bottom" in hero.touching_sides

ship["shield"] @= lambda: st.lives * 10

Não confundir

Avançado

Drivers persistentes

Além de @=, outras coisas também escrevem um campo a cada frame. Só a fórmula @= é exclusiva — as outras se somam, em qualquer ordem.

Um driver persistente é o que escreve pose (ou um campo) sem o autor chamar um verbo pontual a cada frame: a fórmula @=, o arraste do mouse (draggable), a roda (wheel_rotate), um tween / move_to(..., time=) / move_along em voo, ou o resolve() de colisão em pé. Só a fórmula é exclusiva: um campo ligado com @= não aceita nenhum outro driver (e vice-versa), em qualquer ordem. Os outros convivem: um move_by(time=) antes ou depois do resolve() dá o mesmo resultado (para na parede), e um shape draggable pode ter um movimento em voo.

c.draggable = True
# LinkedAttributeError — o center já tem driver (draggable)
# c["center"] @= lambda: src

c.draggable = False
c["center"] @= lambda: src          # agora ok

h = c.move_to(400, 200, time=2.0)
# LinkedAttributeError — "move_to(time=2) pushes it"
# c["center"] @= lambda: src
h.cancel()
c["center"] @= lambda: src

resolve(bola, "parede")
# LinkedAttributeError se bola.center já estiver ligado
unresolve(bola, "parede")

inimigo.draggable = True
inimigo.move_by(200, 0, time=2, loops="forever")   # ok: convivem
# segurar o inimigo com o mouse congela a patrulha nele;
# soltar → ela continua de onde ele caiu

Regra: fórmula @= contra qualquer outro driver na mesma parte → erro duro, nas duas ordens (a mensagem diz a linha onde o objeto foi criado, ex. the Sprite made at jogo.py:151). Os outros drivers nunca se recusam entre si. Segurar com o mouse congela os movimentos (tween / move_*(time=)) nas partes que o arraste (ou a roda) escreve; ao soltar eles continuam, antes do on_drag_to — então um “voltar para casa” (move_to(casa, time=0.3)) no on_drag_to funciona. Enquanto você segura, o arraste vence também o que o seu on_update escreve no objeto (um move_by de gravidade por frame): a cada frame ele volta para baixo do cursor; ao soltar, o seu código volta a mandar. Isso não é handle.pause(): h.paused continua sendo só seu. Redeclaração do mesmo tipo (segundo tween na mesma chave, novo @= no mesmo campo) → avisa e substitui. force=True continua só nos verbos pontuais de Mover / tween — não nos flags draggable / wheel_rotate.

Não confundir

Onde mais procurar — Mover (force=) · Colisão (resolve) · Handle

Todo objeto na tela

O que vale para todo objeto que aparece na tela — Shape, Sprite, Text e SpatialFx: esconder, estacionar, destruir, camada, grupo e .center. Fica aqui uma vez; as seções de cada tipo não repetem.

ship.visible = False
# estacionar: some, para timers e colisão
# (um som do ship continua tocando; o on_done dele espera o ship voltar)
ship.active = False
# cancela timers/tweens/mode; Entity continua viva
ship.cancel_process()
# some de vez. is_alive vira False
ship.destroy()

nave = Sprite("ship.png", layer="ui", group=["wasp", "enemy"])
# nave: a variável é como você acha este objeto depois.
# layer: desenha na camada "ui" (fora da ordem normal do mundo).
# group: entra em group["wasp"] e group["enemy"] ao mesmo tempo.

Não confundir

Shapes

Shapes são as formas geométricas: círculo, retângulo, linha, elipse, polígono, ponto. Aparecem assim que criadas; sem argumentos (Circle()) nascem com um tamanho médio no centro da tela. Todas aceitam color=, visual=, line_width=, layer= e group=.

c = Circle(center=(400, 300), radius=50, color="cyan")
c.set_color("tomato")
c.visual = Neon()
c.show_handles()

set_defaults(visual=Neon())
set_defaults("coral", line_width=2.0, dash="dot")

Modelo de construção incompleto (Circle(p1=…) sem p2) levanta ValueError. Não vira o padrão.

c = Circle(center=(400, 300), radius=50, color="cyan")

c = Circle(center=(400, 300), radius=50)
Circle(p1=(100, 200), p2=(300, 200))   # diâmetro
p = c.point_at_angle(45)               # Point efêmero na borda
dots = Track(c).spaced_points(8)       # 8 tuplas (x, y) no contorno

c = Circle(center=(400, 300), radius=50, color="cyan")
c.set_color("tomato")
c.visual = Neon()

c.move_by(200 * dt, 0)
c.move_by(angle=90, distance=40)
c.move_by(distance=120 * dt)
c.rotate_by(30 * dt)

Rect()
Rect(center=(400, 300), width=120, height=60, color="navy")
Rect(top_left=(80, 200), width=160, height=80)
Rect(center=(400, 200), width=140, height=70, corner_radius=16)
Rect(p1=(100, 300), p2=(300, 300), height=40, anchor="square")

Square()
Square(center=(400, 300), length=80, color="gold")
Square(top_left=(100, 200), length=60)
Square(center=(400, 200), length=70, corner_radius=12)

Line()
Line(center=(240, 160), length=200, angle=30, color="cyan")
Line(p1=(80, 80), p2=(400, 240), color="cyan", line_width=5)
ln.visual = Laser()

Ellipse()
Ellipse(center=(400, 300), width=140, height=70)
Ellipse(from_rect=box, padding=8)

Polygon()
Polygon(points=[(100, 80), (220, 90), (200, 180), (90, 160)], color="coral")
Polygon(points=[(0, 0), (80, 0), (40, 60)], visual=Neon())

RegularPolygon()
RegularPolygon(n=5, center=(400, 300), radius=50, color="cyan")

EquilateralTriangle()
EquilateralTriangle(center=(400, 300), radius=50, color="cyan")
t.rotate_by(30 * dt)

p = Point(200, 150)
p = Point(200, 150, color="cyan")   # guia visível (não arrastável)
p = Point(canvas.game_view.center)  # cópia do centro da vista
p.visible = True
p.handle = True
# Point visível + arrastável no top
a = Anchor(400, 300)
b = Anchor(500, 300, color="lime")

a = Anchor(400, 300)
a = Anchor(400, 300, color="cyan")
a = Anchor(canvas.game_view.center)
b = Anchor(600, 300)
Line(p1=lambda: a.center, p2=lambda: b.center)   # segue o arraste

Sprite

Um Sprite é uma imagem na tela — um PNG parado ou uma animação. O Sprite é o objeto (posição, tamanho, giro, colisão); o Sheet é o catálogo de quadros (frames) e animações (clips) de onde ele tira a imagem, e sozinho não aparece. Um PNG parado não precisa de Sheet. Aqui, “frame” também é cada quadro da animação (frame= escolhe um); “a cada frame” continua sendo cada volta do jogo.

# Um PNG parado: sem Sheet.
pocao = Sprite("pocao.png", height=48, center=(200, 300))

# Um PNG em grade com uma animação: fps= no Sheet registra o clip, e o Sprite já toca.
caracol = Sheet("caracol.png", cols=8, fps=6)
Sprite(caracol, height=36, center=(400, 300))

# Vários clips: o Sheet nomeia, o Sprite escolhe com play.
folha = Sheet("heroi.png", cols=4, rows=3)
folha.clip("andar", [3, 4, 5, 6], fps=12)
folha.clip("pular", [7, 8, 9], fps=10)
heroi = Sprite(folha, height=64, center=(600, 300))
heroi.play("andar")

# Um PNG por frame: * no lugar da parte que muda pega todos,
# em ordem (Idle__000.png, Idle__001.png, …).
ninja = Sheet(anchor="bottom", pixel_size=0.16)
ninja.strip("parado", "ninja/Idle__*.png", fps=8)
ninja.strip("correndo", "ninja/Run__*.png", fps=12)
lutador = Sprite(ninja, center=(800, 300))
lutador.play("correndo")

Tenho estes arquivos → Carregar sprites
Clips, play, tamanhos diferentes por clip → Animar sprites
Virar, apontar, espelhar, inclinar na rampa → Orientar sprites
Forma do colisor, hurtbox, ponto fraco → Hitbox do Sprite
Clone, classe com padrões, Svg, aparência, clique → Recursos adicionais

Não confundir

Sprite · Como fazer

Carregar sprites

Seis formas, conforme os arquivos que você tem. Em todas, o Sheet monta o catálogo e o Sprite coloca.

Sprite("potion.png", height=48, center=(x, y), group="potion")
Sprite(source="shot.png", height=18, center=(x, y))

robo = Sheet("robot/Run (*).png", fps=12)   # Run (1).png, Run (2).png, … em ordem
Sprite(robo, height=56, center=(x, y))       # um clip → começa a tocar

hero = Sheet(["Idle_0.png", "Idle_1.png", "Run_0.png", "Run_1.png"])
# mesmo: Sheet("Idle_0.png", "Idle_1.png", "Run_0.png", "Run_1.png")
hero.clip("idle", [0, 1], fps=6, yoyo=True)
hero.clip("run",  [2, 3], fps=12)
s = Sprite(hero, height=48, center=(x, y))
s.play("run")

space = Sheet("space_sheet.png", atlas="space_sheet.xml")
space.clip("green", ["enemyGreen1.png", "enemyGreen2.png"], fps=6)
enemy = Sprite(space, height=40, center=(x, y))
enemy.play("green")

run = Sheet("hero.png", cols=4, rows=3)
run.clip("walk", [3, 4, 5, 6], fps=12)
run.clip("jump", [7, 8, 9], fps=10)
Sprite(run, center=(200, 400)).play("walk")

snail = Sheet("snail.png", cols=8, fps=6)   # clip "default" em todas as células
Sprite(snail, height=36, center=(x, y))    # um clip → começa a tocar

hero = Sheet("idle.png", cols=4, fps=6, name="idle")
hero.strip("walk", "walk.png", cols=8, fps=12)
hero.strip("jump", "jump.png", cols=4, fps=10)
# nomeado: hero.strip(name="walk", source="walk.png", cols=8, fps=12)
s = Sprite(hero, height=48, center=(x, y))
s.play("walk")

ninja = Sheet(anchor="bottom", pixel_size=0.16)
ninja.strip("parado", "ninja/Idle__*.png", fps=8)
ninja.strip("correndo", "ninja/Run__*.png", fps=12)
ninja.strip("pulando", "ninja/Jump__*.png", fps=10)
heroi = Sprite(ninja, center=(x, y))
heroi.play("correndo")

space = Sheet("space_sheet.png", atlas="space_sheet.xml")
Sprite(space, frame="playerShip1_blue.png", height=48, center=(x, y))
Sprite(space, frame="powerup_bolt.png", height=24, center=(x2, y2))

Defina os clips no Sheet antes (ou enquanto) cria os Sprites. Um Sheet compartilhado por uma frota é o mesmo objeto: um clip novo aparece para todos.

Padrão de arquivos: *

Pacotes de arte costumam trazer um PNG por frame: Run__000.png, Run__001.png… Em vez de listar um por um, escreva o nome com * no lugar da parte que muda. O * quer dizer “qualquer coisa aqui”: o Scena carrega todos os arquivos daquela pasta cujo nome casa, um frame por arquivo, em ordem.

# Sheet: uma animação só; fps= registra o clip.
# Run (1).png, Run (2).png, … Run (8).png
robo = Sheet("robot/Run (*).png", fps=12)
Sprite(robo, height=56, center=(200, 300))

# strip: uma animação por linha, o nome do clip primeiro.
# "parado" = Idle__000.png … Idle__009.png
ninja = Sheet(anchor="bottom", pixel_size=0.16)
ninja.strip("parado", "ninja/Idle__*.png", fps=8)
ninja.strip("correndo", "ninja/Run__*.png", fps=12)
ninja.strip("pulando", "ninja/Jump__*.png", fps=10)
heroi = Sprite(ninja, center=(500, 300))
heroi.play("correndo")

# Entre outros arquivos: o padrão vira os arquivos dele.
mix = Sheet("ninja/Idle__*.png", "ninja/Dead__009.png")

1. Só o * é especial. Ele vale qualquer trecho do nome (até nenhum). O resto vale letra por letra: "ninja/Jump__*.png" não pega Jump_Throw__000.png. Maiúsculas contam: "ninja/idle__*.png" não acha Idle__000.png.
2. Ordem natural. Os números do nome contam como números: Run (2) vem antes de Run (10), com ou sem zeros na frente (Run__002).
3. Uma pasta só. O * vai no nome do arquivo, não na pasta ("*/Run.png" é ValueError). A busca é a de Arquivos de imagem, e vale a primeira pasta que tiver algum arquivo que casa — nunca mistura pastas.
4. Nada casou? O jogo segue. Um quadriculado no lugar e um aviso com o padrão e as pastas onde procurou (e os nomes que só diferem em maiúsculas). O clip existe e toca.
5. Um arquivo por frame. Não há uma imagem para cortar: cols= / rows= / cell= / atlas= com padrão é TypeError, mesmo que só um arquivo case.

Onde vale: onde vários arquivos valem — no Sheet (como source, numa lista ou entre os arquivos extra) e no strip. Sprite("ninja/Run__*.png") é TypeError: um Sprite com nome de arquivo é uma imagem parada. Escreva Sprite(Sheet("ninja/Run__*.png", fps=12)). Os frames ganham o nome do arquivo sem a extensão ("Run__003"), para usar em clip, frame= e showing. Dois arquivos com o mesmo nome em pastas diferentes (idle/1.png e run/1.png) não deixam o nome "1" valer para nenhum dos dois (ValueError citando os dois); use o caminho ("idle/1.png") ou o índice.

Sem padrão, a mesma coisa em lista: ninja.strip("correndo", ["ninja/Run__000.png", "ninja/Run__001.png"], fps=12). Serve para escolher só alguns frames ou mudar a ordem.

Sprite · Como fazer

Animar sprites

O clip mora no Sheet (quais frames, fps, yoyo); o Sprite escolhe com play. Animação é visual, não mode: sobrevive a e.mode = ….

hero = Sheet("hero.png", cols=4, rows=3)
hero.clip("idle", [0, 1, 2], fps=6, yoyo=True)
hero.clip("walk", [3, 4, 5, 6], fps=12)
sprite = Sprite(hero, center=(200, 400))   # 2+ clips → parado no primeiro frame de "idle"
sprite.play("walk")
sprite.play("walk")                        # não faz nada: a animação segue
sprite.frame = 3                           # para a reprodução e mostra a célula 3

hero = Sheet("hero.png", cols=4, rows=3)
hero.clip("idle", [0, 1, 2], fps=6, yoyo=True)
hero.clip("hit", [9, 10], fps=12)
hero.clip("die", [11], fps=8)
sprite = Sprite(hero, center=(200, 400))
sprite.play("hit", loops=1, next="idle")   # uma vez, depois "idle"
sprite.play("die", loops=1)                # uma vez e segura o último frame

# grounded pode oscilar um frame — min_hold evita reiniciar o clip;
# resume=True continua a fase ao voltar (deixe off em reações de uma vez só).
if not grounded:
    sprite.play("jump", min_hold=0.06)
elif sprite.vel.x != 0:
    sprite.play("walk", min_hold=0.08, resume=True)
else:
    sprite.play("idle", min_hold=0.08, resume=True)

ninja = Sheet(anchor="bottom")
ninja.strip("parado", "ninja/Idle__*.png", fps=8)
ninja.strip("deslizando", "ninja/Slide__*.png", fps=12)
heroi = Sprite(ninja, height=70, center=(x, y))   # center = os pés
heroi.play("deslizando")                           # ~56 de altura, no chão

# ou: a escala na arte, uma vez — sem height= em cada Sprite
tiles = Sheet("tiles.png", cell=(16, 16), pixel_size=3)
chao = Sprite(tiles, center=(x, y))                # célula de 16 px × 3 = 48

Sprite · Como fazer

Orientar sprites

Três perguntas diferentes: para onde o PNG aponta (art_angle), para onde o Sprite aponta no mundo (.angle) e quanto o desenho inclina sem mexer no colisor (tilt). flip_x / flip_y espelham.

# A nave está desenhada apontando para cima (+y).
nave = Sprite("nave.png", height=48, art_angle=90)
nave.angle                          # 90: aparece como desenhada

nave.rotate_to(heading(nave, mouse))   # o nariz aponta para o mouse
tiro.move_to(alvo, time=1.2, face=True)
nave.reset_rotation()                  # volta a rest_heading (90)

# O ninja está desenhado olhando para a direita.
if keyp("LEFT"):
    heroi.flip_x = True     # olha para a esquerda; angle passa a 180
elif keyp("RIGHT"):
    heroi.flip_x = False    # angle volta a 0

heroi = Sprite(ninja, hitbox_shape="rect", hitbox_anchor="bottom")

def update(dt):
    heroi.tilt = "ground"   # ou AUTO_GROUND: segue o chão; no ar volta a 0

# Outras formas:
heroi.tilt = 22             # só esse ângulo
heroi.tilt = 0              # desliga

Não confundir

Sprite · Como fazer

Hitbox do Sprite

Com que forma o Sprite colide. Toda hitbox é um Hitbox: a principal (sprite.hitbox) para chão, parede e resolve; extras (add_hitbox) que só detectam — hurtbox, ponto fraco. As duas têm as mesmas propriedades: shape · source · anchor · scale · active · box.

As duas usam os mesmos quatro parâmetros. No construtor do Sprite eles têm o prefixo hitbox_ (o Sprite tem o próprio scale); na hitbox, não: Sprite(hitbox_scale=0.8) é sprite.hitbox.scale = 0.8, e na extra add_hitbox(scale=0.8) / extra.scale = 0.8.

Quando é calculado. Na primeira vez que o Sprite entra na colisão (@collide, resolve, collidable = True). Sprite só decorativo nunca paga. O resultado fica em cache por imagem: cem Sprite("tiro.png") compartilham um único cálculo. Depois a hitbox principal fica congelada enquanto o clip toca — exceto com "each" (a cada frame) e "clip" (a cada troca de clip). Ver: collision.show_colliders() ou Ctrl+Shift+7 — principais de resolve em dourado, outras principais em verde, extras em ciano.

Medir o Sprite

Cada leitura é um Box novo, do jeito que está agora: largura = heroi.hitbox.box.width. As caixas de hitbox são alinhadas à tela (left / right / bottom / top); box e art_box giram com o Sprite. Medir não inscreve nada na colisão.

Sprite("nave.png")                          # "auto": escolhe a forma sozinho
Sprite("bola.png", hitbox_shape="circle")
Sprite("espadachim.png", hitbox_shape="hull")

folha = Sheet("heroi.png", cols=4, rows=3)
folha.clip("parado", [0, 1], fps=6)
folha.clip("correndo", [2, 3, 4, 5], fps=12)
folha.clip("morto", [9, 10, 11], fps=8)
heroi = Sprite(folha, hitbox_shape="rect", hitbox_source=("parado", "correndo"))

# Receita de plataforma: caixa estável, pés no chão, mais estreita que a arte.
heroi = Sprite(
    folha,
    hitbox_shape="rect",
    hitbox_source="all",
    hitbox_anchor="bottom",
    hitbox_scale=(0.55, 1.0),
)

Sprite("espadachim.png", hitbox_shape="hull", hitbox_anchor=(-0.5, 0))

EM_PE = ("parado", "correndo", "pulando")

heroi = Sprite(ninja, group="heroi", hitbox_shape="rect", hitbox_source=EM_PE,
               hitbox_anchor="bottom", hitbox_scale=(0.55, 1.0))

def entrar_na_agua():
    heroi.hitbox.source = ("nadando", "boiando")   # união dos dois clips
    heroi.hitbox.anchor = "center"
    heroi.hitbox.scale = (1.0, 0.55)             # pose horizontal: achata a altura
    heroi.play("nadando")

def sair_da_agua():
    heroi.hitbox.source = EM_PE
    heroi.hitbox.anchor = "bottom"
    heroi.hitbox.scale = (0.55, 1.0)
    heroi.play("parado")

heroi = Sprite(ninja, group="heroi", hitbox_shape="rect", hitbox_source="all",
               hitbox_anchor="bottom", hitbox_scale=(0.55, 1.0))
dor = heroi.add_hitbox(group="dor")      # silhueta do frame atual; só detecta

resolve(heroi, "chao")                    # a principal pisa no chão

@collide("bala", "dor")                   # a parte responde por "dor"
def ferido(bala, alvo, info):             # alvo é o heroi; info.b_hitbox é dor
    alvo.hp -= 1
    bala.destroy()

class Heroi(Sprite):
    def setup(self):
        self.dor = self.add_hitbox(group="dor")

lutador = Sheet("lutador.png", atlas="lutador.json")   # frames com "hitboxes"

# A principal com forma explícita ignora as caixas: fica a silhueta.
p1 = Sprite(lutador, hitbox_shape="rect", hitbox_source="all", hitbox_anchor="bottom")

# Uma extra "auto" + "each" lê as caixas do frame atual.
caixas = p1.add_hitbox(group="golpe")

folha.clip("golpe", [10, 11, 12, 13, 14, 15], fps=14)
GOLPE = (12, 13, 14)                              # frames com a espada esticada

espada = heroi.add_hitbox(group="ataque", px_rect=(430, 180, 90, 80))
espada["active"] @= lambda: heroi.showing(GOLPE)

def atacar():
    heroi.play("golpe", loops=1, next="parado")   # a caixa liga e desliga sozinha

@collide("ataque", "inimigo")
def acertou(heroi, inimigo, info):
    inimigo.destroy()

Não confundir

Sprite

Recursos adicionais do Sprite

Depois do básico: copiar um Sprite, dar padrões a uma classe, usar SVG como sprite, aparência e clique.

class Nave(Sprite, source="playerShip1_blue.png", height=48, group="nave"):
    pass

_NAVE = Nave(layer=None)    # carimbo: fora da tela
_NAVE.active = False        # não roda nem colide
naveA = _NAVE.clone(center=(120, 400))
naveB = _NAVE.clone(center=(240, 400))
naveC = _NAVE.clone(center=(360, 400))

space = Sheet("space_sheet.png", atlas="space_sheet.xml")

class Tiro(Sprite, source=space, frame="laserBlue01.png", height=18,
           art_angle=90, group="tiro"):
    def setup(self):
        self.dano = 1

Tiro(center=nave.center)
Tiro(center=nave.center, frame="laserRed01.png")   # a instância vence

bussola = Svg("compass.svg", height=48, center=(x, y))
Svg("<svg …>", height=48)
bussola.svg = lib.render()   # recarrega (markup ou arquivo)

nave.alpha = 0.5
nave.blend = "add"
nave.glow = True
nave.visual = Halo()
nave.shield_scale = 1.6            # oval do Shield maior que a silhueta

# Tela de carregamento: aquece antes de trocar de visual em jogo.
nave.prepare_fx(Halo, Aura)

Track

Uma curva. Serve para duas coisas: trilha de move_along e traço desenhável (parede curva, anel que se enche). Padrão: invisível, como Point. Qualquer Shape também é trilha: bug.move_along(hexagon, time=4).

orbit = Track.circle(center=lambda: earth.center, radius=120)
moon.move_along(orbit, time=4, loops="forever")
wasp.move_along(Track.eight(width=90, height=40), time=2.5)
track = Track(points=[(80, 200), (240, 380), (520, 160)], color="gold")
t1 = Track(sprite1)

Ancorada ou flutuante. É a decisão que muda o comportamento de uma trilha:

floating= explícito sempre manda. Toda Track tem .center real — flutuar não é “sem posição”; .is_floating só diz se a pose prende quem viaja.

Dar lugar depois ancora. Uma trilha que flutua só porque nasceu sem colocação ancora quando você lhe dá um lugar depois: ligar o centro (orbit["center"] @= lambda: earth.center), escrever .center = ou mover (move_to, move_by). É a colocação que faltou, igual a center= no construtor; quem já viaja nela passa a segui-la. Girar ou escalar não é colocação. Com floating=True (ou is_floating = True) ela continua flutuando: mover só muda onde ela é desenhada.

Visível ou não. Uma trilha só de movimento (sem color= / visual= / line_width= / visible=True / layer=) fica fora da lista de desenho — dá para viajar, e some quando ninguém a segura. Com estilo, visible=True ou layer= explícita, entra no canvas como Shape (traço, clique e colisão). Para ver as trilhas durante o desenvolvimento: show_tracks(True) (magenta; não liga visible) — ver Debug.

Track()                                          # Track.eight(); flutua
Track(points=[(60, 80), (200, 300), (420, 120)]) # curva (smooth=1)
Track(points=[...], smooth=0, closed=True)       # polilinha
Track(vectors=[Vec2(50, 0), (0, 80), (-40, 20)], smooth=0)  # passos relativos, flutua
Track(hexagon)            # contorno vivo; clone() congela
Track(sprite)             # contorno vivo da silhueta (hurtbox é add_hitbox)
Track(ellipse, floating=True)  # contorno vivo; posição não prende quem viaja
Track.circle(center=(400, 300), radius=120)   # ancorado no mundo
Track.eight(width=90, height=40)              # flutua até quem viaja

Track.line(length=200)                        # +x, flutua
Track.line(length=200, angle=90)              # +y
Track.line(vec=Vec2(120, -40))                # tamanho + direção
Track.line(length=400, angle=-30, p1=(1050, 450))  # plantado, u=0 em p1
Track.line(p1=(0, 0), p2=(200, 0))            # dois pontos, ancorado
Track.circle(radius=80, center=(400, 300))
Track.arc(radius=80, from_angle=0, to_angle=180)
Track.eight(width=90, height=40)
Track.eight(width=90, height=40, center=(400, 300), floating=True)  # desenha lá; quem viaja faz o oito a partir de onde está
Track.star(points=5, radius=70)
Track.spiral(turns=3, radius=80)
Track.wave(length=200, amplitude=30, waves=3)
Track.wave(length=200, start=(100, 300))
Track.shuttle(length=180)                     # vai e volta pelos dois lados, fechado

x, y = track.at(0.25)
ang = track.angle_at(0.25)
tx, ty = track.tangent_at(0.25)
pts = track.spaced_points(8)          # fechado: sem repetir o início
pts = Track(linha).spaced_points(5)   # aberto: inclui as pontas
track.u = 0.5
ship["center"] @= lambda: track.cursor   # coloca — para viajar: move_along

ring = Track.circle(center=(400, 300), radius=80, color="gold", line_width=5)
ring.end = 0
tween(ring["end"], 1, time=1.4, ease="ease_out")
# janela que anda num loop (fechado envolve)
crawl = Track.circle(center=(400, 300), radius=100, color="cyan", line_width=4)
crawl.begin = 0
crawl.end = 0.2

base = Track(points=[(80, 200), (520, 200)], smooth=0)
base.zigzag(amount=24, waves=6)     # muda este Track, devolve self
base.orbit(radius=12, laps=4)
base.wander(amount=10, seed=3)
# clone() antes se quiser a reta original

wall = Track.arc(
    center=(400, 300), radius=80, from_angle=0, to_angle=90,
    color="gold", line_width=8, group="wall",
)
resolve(player, "wall", bounce=0.0)

Não confundir

History

Uma History guarda os últimos objetos (ou posições) que você acrescenta e tira os mais velhos sozinha — passando de max_points= ou de duration= segundos. Serve para rastros de peças (bolinhas, segmentos), cobras, filas. Ela não desenha: quem aparece são os objetos que você põe nela (add), e o que sai é destruído. snapshot guarda só uma posição. Para um traço contínuo que esmaece: Contrail.

dots = History(max_points=40, on_leave=lambda dot: dot.dissolve_out(0.3))

def drop_dot():
    dot = dots.add(Circle(center=tip.center, radius=4))
    dot.visual = Halo("cyan")

every(0.05, drop_dot)

segments = History(max_points=100, duration=2.0)

def sample():
    start = segments.last.p2 if segments else tip.center
    segment = segments.add(Line(p1=start, p2=tip.center))
    segment.visual = Laser("red")

every(0.05, sample)

Não confundir

Contrail

Um Contrail desenha um rastro: uma linha contínua pelas últimas posições de um objeto, que pode esmaecer da cabeça para a cauda (fade=). Você só diz quando guardar uma posição — contrail.snapshot(nave), em geral com nave.every(0.05, …) — e o traço se atualiza sozinho. É uma History com um traço, só de posições (add levanta).

trail = Contrail(max_points=100, duration=2.0, fade=True, ease="ease_out",
                 visual=Laser("red"), line_width=3)
dst.every(0.05, lambda: trail.snapshot(dst))  # para no destroy; pausa com dst.active = False

# polilinha facetada
Contrail(smooth=0, line_join="miter", visual=Laser("red"))

# cresce como cobra
trail.max_points += 1

# alpha base (o fade multiplica por cima — cabeça = 0.5, cauda → 0)
Contrail(duration=1.0, color=Color("cyan").with_alpha(0.5), fade=True)

Não confundir

Text

Um texto na tela — placar, legenda, título. Fica preso à janela (HUD) ou no mundo, junto dos objetos, conforme a colocação (tabela abaixo). A caixa acompanha o texto (ou tem width= fixa) e cresce para baixo.

Text("SCORE")                                   # HUD, na coluna automática
hud = Text("", top_left=(20, 780), font_size=20)
hud["text"] @= lambda: f"Stars {st.score}"
Text("HP", center=ship.center)                  # no mundo, anda com a câmera
Text("GAME OVER\nPress SPACE", center=(500, 400))

Linhas. \n é quebra dura (altura = n × métrica). Sem width= a caixa acompanha a linha mais larga; com width=, o excesso corta (sem quebra automática). align= alinha cada linha dentro da caixa e nunca move a âncora. A coluna HUD não se reorganiza se o número de linhas mudar depois da construção.

score = Text("", top_right=(980, 780), font_size=20)
score["text"] @= lambda: f"{st.score}"
Text("READY", top_left=(20, 720), width=160, background="maroon")
Text("Kills 3\nTime 1:02", top_right=(980, 700), align="left")
Text("HP 100/100", center=ship.center, width=120, align="center")

# seguir outro objeto: lambda no ponto (ou num eixo)
panel = Rect(center=(500, 300), width=300, height=120, layer="ui")
Text("Menu", top_left=lambda: panel.top_left)
Text("x", top_left=(lambda: mouse.x, 760))