CUBOGOLF▸ The Grid Protocol v1.0.0

class ErreurParcours(Exception):
    """Parcours invalide. Le message dit quoi et où (« ... en x=12, y=7 »)."""

@dataclass
class Parcours:
    nom: str
    par: int
    largeur: int
    profondeur: int
    types: list                                    # types[cz][cx] -> "herbe", "mur", ...
    depart: tuple                                  # (cx, cz) de la case de départ
    trou: tuple                                    # (cx, cz) de la case du trou
    passages: list = field(default_factory=list)   # [(cx, cz), ...] repères du bot

class Parcours:
    ...
    def type_case(self, cx, cz):
        """Type de la case, 'vide' en dehors de la grille."""
        pass

class Parcours:
    ...
    def centre(self, case):
        """Centre (x, z) d'une case (cx, cz)."""
        pass

def couleur_proche(rgb, reference):
    """Vrai si chacun des trois canaux de rgb est à au plus TOLERANCE_COULEUR de celui de reference."""
    pass

def couleur_vers_type(rgba, x, y):
    """Couleur d'un pixel -> type de case. x, y = position dans l'image.

    Transparent -> 'vide'. Couleur inconnue -> ErreurParcours avec la position.
    """
    pass

def grille(largeur, profondeur, valeur):
    """Une grille de profondeur lignes de largeur cases, toutes à valeur (des lignes DISTINCTES)."""
    pass

def case_du_pixel(x, y, profondeur):
    """Le pixel (x, y) de l'image -> la case (cx, cz) : le haut de l'image est le Nord."""
    pass

def charger_image(chemin, nom="sans nom", par=3):
    """Lit un PNG et renvoie un Parcours vérifié (un seul départ, un seul trou)."""
    pass

def lister_trous(dossier=C.DOSSIER_TROUS):
    """La liste de trous.json : [{"image", "nom", "par"}, ...] dans l'ordre de jeu."""
    pass

def charger_trou(numero, dossier=C.DOSSIER_TROUS):
    """Charge le trou n° numero (1 = le premier de trous.json)."""
    pass

def numero_voisin(numero, total, sens):
    """Le trou suivant (sens=+1) ou précédent (sens=-1) parmi 1..total, en boucle : 9 -> 1, 1 -> 9."""
    pass

def lister_balles(dossier=None):
    """Noms des balles disponibles (le nom du fichier sans .png), triés, la balle par défaut d'abord."""
    pass

def chemin_balle(nom, dossier=None):
    """Chemin du PNG d'une balle ; la balle par défaut si ce nom n'existe pas."""
    pass

def nom_score(coups, par):
    """Nom du score d'un trou : nom_score(1, 3) -> "Trou en un", nom_score(4, 3) -> "Bogey"."""
    pass

def bilan(coups, pars):
    """Compte les scores spéciaux d'un joueur sur toute la partie.

    coups = [3, 1, 2], pars = [3, 3, 3] -> {"Trou en un": 1, "Birdie": 1}  (le par ne compte pas)
    Renvoie seulement les noms de SPECIAUX, dans cet ordre, avec un compte > 0.
    """
    pass

def texte_bilan(coups, pars):
    """Le bilan en une ligne : "1 trou en un, 2 birdies", ou "" s'il n'y a rien."""
    pass

def classement(joueurs):
    """joueurs = [{"nom": ..., "coups": [...]}, ...] -> la même liste triée par total de coups.

    Chaque joueur reçoit un champ "total" et un champ "rang" (ex aequo = même rang).
    """
    pass

def option(cle):
    """La description (un dict de OPTIONS) de l'option qui a cette clé. KeyError si elle n'existe pas."""
    pass

def choix_possibles(o):
    """La liste des valeurs d'une option « choix ». Pour la balle : les fichiers de assets/balles/."""
    pass

def charger(fichier=None):
    """Les réglages du fichier (reglages.json par défaut), complétés par les valeurs par défaut.

    Fichier absent ou abîmé : les valeurs par défaut (le jeu ne doit jamais planter pour ça).
    """
    pass

def sauver(reglages, fichier=None):
    """Écrit les réglages dans le fichier (reglages.json par défaut), en JSON lisible."""
    pass

def voisin(liste, valeur, sens):
    """L'élément après (sens=+1) ou avant (sens=-1) valeur dans liste, en boucle.

    Une valeur absente de la liste compte comme le premier élément.
    """
    pass

def changer(reglages, cle, sens, maxi=None):
    """Change une option d'un cran : sens = +1 (bouton +) ou -1 (bouton -).

    maxi remplace le maximum de l'option (ex. le nombre de trous). Renvoie la nouvelle valeur.
    """
    pass

def texte_valeur(reglages, cle):
    """La valeur telle qu'on l'affiche dans le menu."""
    pass

def resume_bots(reglages):
    """« sans bot », « 1 bot moyen », « 3 bots fort » : pour le texte des boutons du menu."""
    pass

def cube_case(parcours, cx, cz):
    """Le cube de la case (cx, cz) : (couleur rgb, position, taille), ou None pour le vide.

    Le cube va du fond (C.FOND) jusqu'au dessus de la case ; une rampe : jusqu'à mi-hauteur, en orange.
    """
    pass

def creer_monde_cubes(parcours):
    """Un cube de couleur par case (voir cube_case), enfants d'une seule Entity, et le décor du trou."""
    pass

def decor_trou(parcours, monde):
    """Le trou (carré noir) et son drapeau."""
    pass

def direction(angle_deg):
    """Vecteur unitaire (dx, dz) d'un angle de tir (0 = Est, 90 = Nord)."""
    pass

def position_camera(cible, angle_deg, tangage_deg, distance):
    """Position (x, y, z) de la caméra : derrière la cible, dans l'axe du tir, en hauteur."""
    pass

def borner(v, mini, maxi):
    """v ramené entre mini et maxi."""
    pass

class Visee(Entity):
    ...
    def tourner(self, dt):
        """Clavier et souris -> angle, tangage."""
        pass

class Visee(Entity):
    ...
    def placer_camera(self, dt):
        """Place la caméra derrière la cible (lissée), en montant si un mur la cache,
        et la fait regarder la cible."""
        pass

class Visee(Entity):
    ...
    def placer_fleche(self):
        """Montre la flèche de visée devant la balle quand on peut tirer (plus longue quand on charge)."""
        pass

class Visee(Entity):
    ...
    def update(self):
        """À chaque image : tourner, placer la caméra et la flèche, faire avancer la jauge."""
        pass

class Visee(Entity):
    ...
    def input(self, touche):
        """Molette : zoom. Espace / clic gauche : commencer à charger ; relâcher : tirer."""
        pass

class Hud(Entity):
    ...
    def temps(self, secondes):
        """Chrono en haut à droite ; rouge sous 10 s. None pour le cacher."""
        pass

class Jeu(Entity):
    ...
    def charger(self, numero):
        """Charge le trou numero : construit le décor (cubes ou texturé), remet la balle au départ
        (sauf en visite), met à jour le HUD et annonce le nom du trou."""
        pass

class Jeu(Entity):
    ...
    def cible_camera(self):
        """Ce que la caméra regarde : la balle dessinée, ou le milieu du parcours en visite."""
        pass

class Jeu(Entity):
    ...
    def hauteur_terrain(self, x, z):
        """La hauteur du terrain en (x, z) pour la caméra (None en visite : pas de collision)."""
        pass

class Jeu(Entity):
    ...
    def peut_tirer(self):
        """Vrai si on a une balle, à l'arrêt, et que le trou n'est pas fini."""
        pass

class Jeu(Entity):
    ...
    def update(self):
        """À chaque image : lire les messages du réseau, faire glisser et rouler les balles des autres,
        faire avancer la physique (sauf en pause hors ligne), afficher la jauge."""
        pass

class Jeu(Entity):
    ...
    def input(self, touche):
        """Touches de la partie : Tab (scores), Entrée (prêt), N / P (visite), R (entraînement)."""
        pass

class Cubogolf(Entity):
    ...
    def cubes(self):
        """Vrai si le rendu doit être en cubes (réglage, ou --cubes en ligne de commande)."""
        pass

class Cubogolf(Entity):
    ...
    def montrer(self, ecran):
        """Remplace l'écran de menu affiché par ecran (None = plus aucun écran)."""
        pass

class Cubogolf(Entity):
    ...
    def appliquer(self):
        """Applique tout de suite ce qui peut l'être (le reste servira à la prochaine partie)."""
        pass

class Cubogolf(Entity):
    ...
    def lancer_local(self, mode, trou=None):
        """Entraînement ou visite : une partie sans réseau, sur le trou demandé (sinon celui des réglages)."""
        pass

class Cubogolf(Entity):
    ...
    def lancer(self, mode, hote=None, trou=None):
        """mode : solo, heberger, rejoindre, entrainement, visite.

        hote et trou remplacent les réglages pour cette fois (raccourcis de la ligne de commande).
        """
        pass

class Cubogolf(Entity):
    ...
    def menu(self):
        """Affiche l'écran d'accueil."""
        pass

class Cubogolf(Entity):
    ...
    def input(self, touche):
        """Échap : ouvre la pause, ferme les Réglages, ou reprend la partie."""
        pass

@dataclass
class Balle:
    x: float
    y: float
    z: float
    vx: float = 0.0
    vy: float = 0.0
    vz: float = 0.0
    etat: str = "arret"
    coups: int = 0
    dernier_tir: tuple = (0.0, 0.0, 0.0)   # où revenir après l'eau ou le vide

class Balle:
    ...
    def vitesse_sol(self):
        """Norme de la vitesse horizontale."""
        pass

class Balle:
    ...
    def position(self):
        pass

def hauteur_sol(parcours, x, z):
    """Hauteur du terrain au point (x, z), ou None au-dessus du vide.

    Une rampe monte de 0 à HAUTEUR_HAUT dans sa direction : on regarde où on
    est DANS la case (fx, fz entre 0 et 1) pour savoir à quelle hauteur.
    """
    pass

def pente(parcours, x, z):
    """Pente (dh/dx, dh/dz) du terrain sous (x, z). (0, 0) hors des rampes."""
    pass

def frottement(parcours, x, z):
    """Décélération (unités/s²) du sol sous (x, z) : sable, glace, sinon herbe."""
    pass

def bloque(parcours, x, z, y):
    """Vrai si le terrain en (x, z) est une marche plus haute que la balle (mur, flanc de rampe)."""
    pass

def nouvelle_balle(parcours):
    """Balle immobile au centre de la case de départ."""
    pass

def tirer(balle, angle_deg, puissance):
    """Lance la balle. angle_deg : 0 = Est (+x), 90 = Nord (+z). puissance : 0 à 1."""
    pass

def replacer(balle):
    """Retour à la position du dernier tir, +1 coup (eau ou vide)."""
    pass

def ralentir(balle, deceleration, dt):
    """Réduit la vitesse horizontale de deceleration × dt, sans changer sa direction ni passer sous 0."""
    pass

def appliquer_forces(balle, parcours, dt):
    """Au sol : la pente puis le frottement. En l'air : la gravité."""
    pass

def bord(position, vitesse):
    """Le bord de la balle qui avance : un rayon plus loin, dans le sens de la vitesse."""
    pass

def heurter_murs(balle, parcours, dt):
    """Déplace la balle à l'horizontale ; rebondit sur les murs, axe par axe. Vrai si elle a touché."""
    pass

def suivre_sol(balle, h, dt, evenements):
    """Balle au sol : elle suit le terrain (hauteur h), ou décolle s'il n'y a plus de sol sous elle."""
    pass

def tombe_dans_le_trou(balle, parcours):
    """Vrai si la balle est au-dessus du trou ET assez lente pour y tomber."""
    pass

def s_arrete(balle, parcours):
    """Vrai si la balle est assez lente pour s'arrêter, et pas sur une rampe (elle redescendrait)."""
    pass

def sous_pas(balle, parcours, dt, evenements):
    """Un petit pas de temps. Ajoute ce qui se passe dans la liste evenements."""
    pass

def pas(balle, parcours, dt=C.PAS_PHYSIQUE):
    """Avance la balle de dt secondes. Renvoie la liste des événements.

    Événements : 'mur', 'decollage', 'rebond', 'atterrissage', 'eau', 'vide',
    'trou', 'arret'. Si la balle va vite, on découpe dt en petits sous-pas
    pour qu'elle ne traverse jamais un mur.
    """
    pass

def simuler_tir(parcours, balle, angle_deg, puissance, duree_max=30.0, trace=False):
    """Simule un tir jusqu'à l'arrêt, SANS toucher à la balle donnée (on joue une copie).

    Renvoie (balle_finale, evenements, trajectoire). trajectoire = [(x, y, z), ...]
    si trace=True, sinon [].
    """
    pass

def jauge(temps_appuye):
    """Puissance 0 -> 1 -> 0 -> ... selon le temps passé à appuyer (en dents de scie aller-retour)."""
    pass

def lisser(actuel, cible, vitesse, dt):
    """Rapproche actuel de cible en douceur (marche pour un nombre ou un tuple).

    À chaque image on fait une partie du chemin : 1 - e^(-vitesse*dt).
    Ça donne le même mouvement quel que soit le nombre d'images par seconde.
    """
    pass

def interpoler(avant, apres, a):
    """Le point à la fraction a (0 = avant, 1 = apres) du chemin entre deux positions (x, y, z)."""
    pass

def distance_libre(cible, camera_pos, hauteur, marge=0.35, echantillons=24):
    """Distance max avant que le terrain ne cache la cible.

    hauteur : fonction (x, z) -> hauteur du terrain, ou None au-dessus du vide.
    """
    pass

class Visee(Entity):
    ...
    def placer_camera(self, dt):
        """Place la caméra derrière la cible (lissée), en montant si un mur la cache,
        et la fait regarder la cible."""
        pass

class Visee(Entity):
    ...
    def placer_fleche(self):
        """Montre la flèche de visée devant la balle quand on peut tirer (plus longue quand on charge)."""
        pass

class Visee(Entity):
    ...
    def update(self):
        """À chaque image : tourner, placer la caméra et la flèche, faire avancer la jauge."""
        pass

class Visee(Entity):
    ...
    def input(self, touche):
        """Molette : zoom. Espace / clic gauche : commencer à charger ; relâcher : tirer."""
        pass

def ligne_trou(numero, total, nom, par, coups):
    """Le texte du haut de l'écran : « Trou 2/9 - Le virage  (par 3)    Coups : 1 »."""
    pass

class Hud(Entity):
    ...
    def trou(self, numero, total, parcours, coups):
        """Met à jour la ligne du haut (voir ligne_trou)."""
        pass

class Hud(Entity):
    ...
    def puissance(self, p):
        """p entre 0 et 1, ou None pour cacher la jauge."""
        pass

class Hud(Entity):
    ...
    def annonce(self, texte, duree=1.8):
        """Gros texte au centre, effacé après duree secondes (sauf si remplacé avant)."""
        pass

class Hud(Entity):
    ...
    def _effacer(self, jeton):
        """Efface le texte du centre, sauf si une annonce plus récente l'a remplacé."""
        pass

class Hud(Entity):
    ...
    def montrer_panneau(self, texte):
        """Affiche un texte au centre de l'écran sur un fond sombre (scores, salon...)."""
        pass

class Hud(Entity):
    ...
    def cacher_panneau(self):
        """Cache le panneau et son fond."""
        pass

class Jeu(Entity):
    ...
    def maj_hud(self):
        """Réécrit la ligne du haut : trou, nom, par, coups."""
        pass

class Jeu(Entity):
    ...
    def charger(self, numero):
        """Charge le trou numero : construit le décor (cubes ou texturé), remet la balle au départ
        (sauf en visite), met à jour le HUD et annonce le nom du trou."""
        pass

class Jeu(Entity):
    ...
    def peut_tirer(self):
        """Vrai si on a une balle, à l'arrêt, et que le trou n'est pas fini."""
        pass

class Jeu(Entity):
    ...
    def hauteur_terrain(self, x, z):
        """La hauteur du terrain en (x, z) pour la caméra (None en visite : pas de collision)."""
        pass

class Jeu(Entity):
    ...
    def tirer(self, angle, puissance):
        """Tire la balle, met à jour le HUD, prévient le serveur (shot) en ligne."""
        pass

class Jeu(Entity):
    ...
    def avancer(self, dt):
        """Pas fixes de 1/60 s pour rattraper dt (au plus 0,25 s d'un coup). Renvoie les événements."""
        pass

class Jeu(Entity):
    ...
    def dessiner_balle(self):
        """Place la sphère entre le pas précédent et le pas actuel (interpolation), et la fait rouler au sol."""
        pass

class Jeu(Entity):
    ...
    def annoncer(self, evenements):
        """Les annonces des événements de ce tour : eau, vide (et le HUD, car un coup a été ajouté)."""
        pass

class Jeu(Entity):
    ...
    def physique(self):
        """À chaque image : les pas de physique, le dessin de la balle, les annonces, la fin du trou,
        l'envoi de sa position en ligne."""
        pass

class Jeu(Entity):
    ...
    def trou_fini(self):
        """Le trou est fini (balle dans le trou ou COUPS_MAX) : annonce le score spécial ;
        en ligne envoie holed, en entraînement charge le trou suivant après 2,5 s."""
        pass

class Jeu(Entity):
    ...
    def update(self):
        """À chaque image : lire les messages du réseau, faire glisser et rouler les balles des autres,
        faire avancer la physique (sauf en pause hors ligne), afficher la jauge."""
        pass

def perdue(balle, parcours):
    """'eau' si la balle roule sur l'eau, 'vide' si elle est tombée trop bas, sinon None."""
    pass

def sous_pas(balle, parcours, dt, evenements):
    """Un petit pas de temps. Ajoute ce qui se passe dans la liste evenements."""
    pass

def suivre_sol(balle, h, dt, evenements):
    """Balle au sol : elle suit le terrain (hauteur h), ou décolle s'il n'y a plus de sol sous elle."""
    pass

def appliquer_forces(balle, parcours, dt):
    """Au sol : la pente puis le frottement. En l'air : la gravité."""
    pass

def voler(balle, h, dt, evenements):
    """Balle en l'air : elle tombe ; au contact du sol (hauteur h), elle rebondit ou se pose."""
    pass

def sous_pas(balle, parcours, dt, evenements):
    """Un petit pas de temps. Ajoute ce qui se passe dans la liste evenements."""
    pass

def hauteur_rampe(type_case, fx, fz):
    """Hauteur d'une rampe au point (fx, fz) de sa case (fx, fz entre 0 et 1) : de 0 à HAUTEUR_HAUT."""
    pass

def hauteur_sol(parcours, x, z):
    """Hauteur du terrain au point (x, z), ou None au-dessus du vide.

    Une rampe monte de 0 à HAUTEUR_HAUT dans sa direction : on regarde où on
    est DANS la case (fx, fz entre 0 et 1) pour savoir à quelle hauteur.
    """
    pass

def pente(parcours, x, z):
    """Pente (dh/dx, dh/dz) du terrain sous (x, z). (0, 0) hors des rampes."""
    pass

def appliquer_forces(balle, parcours, dt):
    """Au sol : la pente puis le frottement. En l'air : la gravité."""
    pass

def s_arrete(balle, parcours):
    """Vrai si la balle est assez lente pour s'arrêter, et pas sur une rampe (elle redescendrait)."""
    pass

def voler(balle, h, dt, evenements):
    """Balle en l'air : elle tombe ; au contact du sol (hauteur h), elle rebondit ou se pose."""
    pass

def suivre_sol(balle, h, dt, evenements):
    """Balle au sol : elle suit le terrain (hauteur h), ou décolle s'il n'y a plus de sol sous elle."""
    pass

class ErreurProtocole(Exception):
    pass

def message(type_message, **champs):
    """Construit un message et vérifie qu'il ne manque aucun champ.

    message("join", nom="Zoé") -> {"type": "join", "nom": "Zoé"}
    """
    pass

def arrondir(pos):
    """Arrondit une position à 2 décimales pour alléger les messages."""
    pass

def encoder(msg):
    """dict -> octets prêts à envoyer (JSON + \\n)."""
    pass

def decoder(ligne):
    """Une ligne (octets, sans \\n) -> dict. Lève ErreurProtocole si invalide."""
    pass

class Decoupeur:
    ...
    def __init__(self):
        """Un découpeur neuf : tampon vide (b"")."""
        pass

class Decoupeur:
    ...
    def ajouter(self, donnees):
        """Ajoute des octets reçus, renvoie la liste des messages complets (peut être vide)."""
        pass

class Salon:
    ...
    def envoyer(self, msg, a=None):
        """Prépare un message : a = id du destinataire, None = tout le monde."""
        pass

class Salon:
    ...
    def prendre_sorties(self):
        """Renvoie les messages en attente et vide la liste."""
        pass

class Salon:
    ...
    def humains(self):
        """La liste des joueurs qui ne sont pas des bots."""
        pass

class Salon:
    ...
    def envoyer_lobby(self):
        """Envoie à tous un message lobby : [{id, nom, pret, bot, balle}] pour chaque joueur."""
        pass

class Salon:
    ...
    def ajouter_joueur(self, nom, balle=PAR_DEFAUT):
        """Un client vient de se connecter. Renvoie son identifiant."""
        pass

class Salon:
    ...
    def retour_salon(self):
        """Retour à la phase salon : on efface les scores et les pars, les humains ne sont plus prêts."""
        pass

class Salon:
    ...
    def retirer_joueur(self, ident):
        """Un client s'est déconnecté : il ne bloque plus rien."""
        pass

class Salon:
    ...
    def joueur_pret(self, j):
        """j est prêt. Au salon ou en fin de partie, si TOUS les humains sont prêts, la partie (re)commence."""
        pass

class Salon:
    ...
    def joueur_fini(self, j, coups):
        """j a fini le trou. Le premier qui finit réduit le chrono des autres."""
        pass

class Salon:
    ...
    def recevoir(self, ident, msg):
        """Un message est arrivé du joueur ident."""
        pass

class Salon:
    ...
    def trou_suivant(self):
        """Passe au trou suivant (ou à la fin de partie après le dernier) : charge le parcours,
        note son par, remet le chrono à temps_limite, remet les joueurs à zéro, place les balles des bots,
        envoie start_hole."""
        pass

class Salon:
    ...
    def fin_du_trou(self):
        """Note le score de chacun (COUPS_MAX s'il n'a pas fini), envoie scores (avec les pars),
        passe en phase scores."""
        pass

class Salon:
    ...
    def fin_de_partie(self):
        """Phase fin : envoie end avec le classement (au total des coups, avec le bilan des scores
        spéciaux de chacun). Les humains ne sont plus prêts (pour rejouer)."""
        pass

class Salon:
    ...
    def etat_balles(self):
        """{id: {nom, pos, etat, coups, fini, bot, balle}} pour chaque joueur : le contenu du message balls."""
        pass

class Salon:
    ...
    def tick(self, dt):
        """Le temps avance de dt secondes (appelé ~20 fois par seconde)."""
        pass

def distance(a, b):
    """Distance entre deux points (x, z)."""
    pass

def ligne_libre(parcours, a, b):
    """Vrai si le segment a -> b (points (x, z)) ne traverse ni mur, ni eau, ni vide.

    On regarde des points tous les 0.2 le long du segment.
    """
    pass

class GolfeurBot:
    ...
    def __init__(self, niveau="moyen", rng=None):
        """niveau : 'facile', 'moyen' ou 'fort' (sinon ValueError). rng : un random.Random (pour des tests reproductibles)."""
        pass

class GolfeurBot:
    ...
    def choisir_cible(self, parcours, balle):
        """(x, z) visé : le trou s'il est visible, sinon le meilleur point de passage."""
        pass

class GolfeurBot:
    ...
    def note(self, balle, fin, cible):
        """Note d'un tir simulé : plus petit = meilleur."""
        pass

def angle_vers(depart, cible):
    """Angle en degrés (0 = Est, 90 = Nord) pour aller du point depart (x, z) au point cible (x, z)."""
    pass

class GolfeurBot:
    ...
    def essayer(self, parcours, balle, cible, angles):
        """Simule chaque angle avec chaque puissance de PUISSANCES. Renvoie ((angle, puissance), note) du meilleur."""
        pass

class GolfeurBot:
    ...
    def meilleur_tir(self, parcours, balle):
        """Le tir parfait (angle_deg, puissance), sans erreur."""
        pass

class GolfeurBot:
    ...
    def choisir_tir(self, parcours, balle):
        """Le tir joué (angle_deg, puissance), avec l'erreur du niveau."""
        pass

class Salon:
    ...
    def jouer_bot(self, j, dt):
        """Fait avancer un bot : attendre, choisir un tir, puis simuler la balle."""
        pass

class Salon:
    ...
    def tick(self, dt):
        """Le temps avance de dt secondes (appelé ~20 fois par seconde)."""
        pass

class ClientReseau:
    ...
    @staticmethod
    def connecter(hote, port, delai):
        """Le serveur peut mettre un instant à démarrer : on réessaie."""
        pass

class ClientReseau:
    ...
    def __init__(self, hote="127.0.0.1", port=C.PORT, nom="Joueur", balle="blanche", delai=5.0):
        """Se connecte (en réessayant jusqu'à delai secondes) et envoie « join » avec sa balle."""
        pass

class ClientReseau:
    ...
    def lire(self):
        """Thread réseau : reçoit, découpe, dépose dans la file."""
        pass

class ClientReseau:
    ...
    def envoyer(self, msg):
        """Envoie un message (dict). Ne plante pas si la connexion est coupée."""
        pass

class ClientReseau:
    ...
    def messages(self):
        """Tous les messages reçus depuis le dernier appel (sans attendre)."""
        pass

class ClientReseau:
    ...
    def attendre(self, type_message, delai=5.0):
        """Attend un message d'un type donné (outils et tests). None si trop long."""
        pass

class ClientReseau:
    ...
    def fermer(self):
        """Ferme la connexion proprement (le thread de lecture s'arrête tout seul)."""
        pass

class Cubogolf(Entity):
    ...
    def arreter_serveur(self):
        """Arrête le serveur local s'il y en a un."""
        pass

class Cubogolf(Entity):
    ...
    def lancer_en_ligne(self, mode, hote=None):
        """Solo, héberger ou rejoindre : (démarrer le serveur local), se connecter, créer la partie."""
        pass

class Cubogolf(Entity):
    ...
    def lancer(self, mode, hote=None, trou=None):
        """mode : solo, heberger, rejoindre, entrainement, visite.

        hote et trou remplacent les réglages pour cette fois (raccourcis de la ligne de commande).
        """
        pass

def texte_salon(joueurs):
    """joueurs [{nom, pret, bot}] -> liste lisible du salon."""
    pass

class Jeu(Entity):
    ...
    def tirer(self, angle, puissance):
        """Tire la balle, met à jour le HUD, prévient le serveur (shot) en ligne."""
        pass

class Jeu(Entity):
    ...
    def envoyer_position(self, dt):
        """Envoie sa balle au serveur (message ball), FREQUENCE_RESEAU fois par seconde, pas à chaque image."""
        pass

class Jeu(Entity):
    ...
    def physique(self):
        """À chaque image : les pas de physique, le dessin de la balle, les annonces, la fin du trou,
        l'envoi de sa position en ligne."""
        pass

class Jeu(Entity):
    ...
    def trou_fini(self):
        """Le trou est fini (balle dans le trou ou COUPS_MAX) : annonce le score spécial ;
        en ligne envoie holed, en entraînement charge le trou suivant après 2,5 s."""
        pass

class Jeu(Entity):
    ...
    def creer_autre(self, ident, info, position):
        """La sphère d'un autre joueur : sa texture, son nom au-dessus, une couleur par joueur."""
        pass

class Jeu(Entity):
    ...
    def maj_autres(self, balles):
        """Crée, met à jour ou supprime les balles des autres joueurs."""
        pass

class Jeu(Entity):
    ...
    def recevoir(self, msg):
        """Réagit à un message du serveur : welcome, lobby, start_hole, balls (balles, chrono,
        premier), scores, end, deconnecte."""
        pass

class Jeu(Entity):
    ...
    def sur_balls(self, msg):
        """Message balls (20 fois par seconde) : les balles des autres, le chrono, et l'annonce
        quand un premier joueur vient de finir."""
        pass

class Jeu(Entity):
    ...
    def maj_reseau(self):
        """Traite les messages reçus, puis fait glisser (et rouler) les balles des autres vers leur position reçue."""
        pass

class Jeu(Entity):
    ...
    def update(self):
        """À chaque image : lire les messages du réseau, faire glisser et rouler les balles des autres,
        faire avancer la physique (sauf en pause hors ligne), afficher la jauge."""
        pass

class Jeu(Entity):
    ...
    def input(self, touche):
        """Touches de la partie : Tab (scores), Entrée (prêt), N / P (visite), R (entraînement)."""
        pass

class MenuPrincipal(Ecran):
    ...
    def __init__(self, controleur):
        """L'accueil : un bouton par mode (avec les réglages utiles dans le texte), Réglages, Quitter."""
        pass

class EcranReglages(Ecran):
    ...
    def ligne(self, o, y, maxi):
        """Une ligne de l'écran pour l'option o, à la hauteur y : son libellé, puis un champ de texte,
        ou - valeur + (maxi : le maximum à donner à changer). Pour la balle, un aperçu."""
        pass

class EcranReglages(Ecran):
    ...
    def __init__(self, controleur, depuis):
        """Une ligne par option de reglages.OPTIONS : un champ de texte, ou des boutons - et +
        autour de la valeur. depuis = 'menu' ou 'pause' (où revenir). Un aperçu de la balle qui tourne."""
        pass

class EcranReglages(Ecran):
    ...
    def afficher(self):
        """Réécrit toutes les valeurs affichées (et la texture de l'aperçu de la balle)."""
        pass

class EcranReglages(Ecran):
    ...
    def update(self):
        """Fait tourner l'aperçu de la balle."""
        pass

class EcranReglages(Ecran):
    ...
    def cliquer(self, cle, sens, maxi):
        """Bouton - ou + : change l'option d'un cran, réaffiche, prévient le contrôleur."""
        pass

class EcranReglages(Ecran):
    ...
    def taper(self, cle, texte):
        """Un champ de texte a changé : on garde le texte et on prévient le contrôleur."""
        pass

class MenuPause(Ecran):
    ...
    def __init__(self, controleur, en_ligne):
        """Reprendre, Réglages, Retour au menu, Quitter (+ une note si la partie est en ligne)."""
        pass

class Cubogolf(Entity):
    ...
    def menu(self):
        """Affiche l'écran d'accueil."""
        pass

class Cubogolf(Entity):
    ...
    def ouvrir_reglages(self, depuis):
        """Affiche l'écran Réglages ; depuis = 'menu' ou 'pause'."""
        pass

class Cubogolf(Entity):
    ...
    def fermer_reglages(self, depuis):
        """Quitte les Réglages : retour à la pause ou à l'accueil, selon depuis."""
        pass

class Cubogolf(Entity):
    ...
    def reglages_changes(self):
        """Un réglage a changé : on sauvegarde et on applique."""
        pass

class Cubogolf(Entity):
    ...
    def appliquer(self):
        """Applique tout de suite ce qui peut l'être (le reste servira à la prochaine partie)."""
        pass

class Cubogolf(Entity):
    ...
    def pause(self):
        """Met la partie en pause et affiche le menu pause."""
        pass

class Cubogolf(Entity):
    ...
    def reprendre(self):
        """Ferme le menu pause et relance la partie."""
        pass

class Cubogolf(Entity):
    ...
    def retour_menu(self):
        """Quitte la partie (et le serveur local), affiche l'accueil."""
        pass

class Cubogolf(Entity):
    ...
    def input(self, touche):
        """Échap : ouvre la pause, ferme les Réglages, ou reprend la partie."""
        pass

class Jeu(Entity):
    ...
    def mettre_en_pause(self, pause):
        """Hors ligne, tout s'arrête. En ligne, la partie continue mais on ne vise plus."""
        pass

class Jeu(Entity):
    ...
    def update(self):
        """À chaque image : lire les messages du réseau, faire glisser et rouler les balles des autres,
        faire avancer la physique (sauf en pause hors ligne), afficher la jauge."""
        pass

class Jeu(Entity):
    ...
    def quitter(self):
        """Détruit tout ce que la partie a créé et ferme la connexion."""
        pass

class Jeu(Entity):
    ...
    def changer_rendu(self, cubes):
        """Réglage « Rendu » changé en cours de partie : on reconstruit le décor."""
        pass

class Jeu(Entity):
    ...
    def input(self, touche):
        """Touches de la partie : Tab (scores), Entrée (prêt), N / P (visite), R (entraînement)."""
        pass