📚 API de Référence - KodLab

Documentation complète de toutes les fonctions disponibles dans le langage Kod.

---

📋 Table des Matières

1. API Graphique
2. API d'Entrées
3. Fonctions de Jeu
4. Utilitaires
5. Constantes
6. Exemples d'Usage

---

API Graphique

Gestion de l'Écran

clearScreen(color)

Efface tout l'écran avec la couleur spécifiée.

Paramètres: - color (string) : Couleur au format hexadécimal ou nom

Exemples:

clearScreen("#000000")    // Noir
clearScreen("#FFFFFF")    // Blanc
clearScreen("#001122")    // Bleu foncé
clearScreen("red")        // Rouge (noms limités)

Notes: - À appeler une seule fois par frame, au début de update() - Obligatoire pour éviter les trainées d'affichage - Performance optimisée pour les couleurs hexadécimales

---

Formes Géométriques

drawRect(x, y, width, height, color)

Dessine un rectangle plein.

Paramètres: - x (number) : Position X du coin supérieur gauche - y (number) : Position Y du coin supérieur gauche
- width (number) : Largeur du rectangle - height (number) : Hauteur du rectangle - color (string) : Couleur de remplissage

Exemples:

drawRect(100, 50, 80, 40, "#FF0000")     // Rectangle rouge
drawRect(0, 0, 400, 20, "#333333")       // Barre supérieure
drawRect(playerX, playerY, 20, 20, "#00FF00")  // Joueur carré

Cas d'Usage: - Plateformes et obstacles - Interface utilisateur (barres, boutons) - Joueurs et ennemis rectangulaires

---

drawCircle(x, y, radius, color)

Dessine un cercle plein.

Paramètres: - x (number) : Position X du centre - y (number) : Position Y du centre - radius (number) : Rayon du cercle - color (string) : Couleur de remplissage

Exemples:

drawCircle(200, 150, 25, "#FFFF00")      // Cercle jaune centré
drawCircle(ballX, ballY, ballRadius, "#FFFFFF")  // Balle
drawCircle(mouseX, mouseY, 5, "#FF0000")         // Curseur

Cas d'Usage: - Balles et projectiles - Joueurs circulaires - Particules et effets - Zones de collision visibles

---

drawLine(x1, y1, x2, y2, color)

Dessine une ligne droite.

Paramètres: - x1 (number) : Position X du point de départ - y1 (number) : Position Y du point de départ - x2 (number) : Position X du point d'arrivée - y2 (number) : Position Y du point d'arrivée - color (string) : Couleur de la ligne

Exemples:

drawLine(0, 150, 400, 150, "#666666")    // Ligne horizontale
drawLine(0, 0, 400, 300, "#FFFFFF")      // Diagonale
drawLine(playerX, playerY, targetX, targetY, "#FF0000")  // Visée

Cas d'Usage: - Trajectoires et visées - Grilles et repères - Connexions entre objets - Décoration et interface

---

drawPixel(x, y, color)

Dessine un pixel unique.

Paramètres: - x (number) : Position X du pixel - y (number) : Position Y du pixel - color (string) : Couleur du pixel

Exemples:

drawPixel(200, 150, "#FFFFFF")           // Pixel blanc
for i = 1 to 100
    drawPixel(randomX, randomY, "#FFFF00")  // Étoiles
end

Cas d'Usage: - Effets de particules - Étoiles et points lumineux - Pixel art détaillé - Debuggage de positions

Notes: - Performance modérée : éviter les milliers de pixels par frame - Idéal pour les détails fins

---

Texte et Interface

drawText(text, x, y, color)

Affiche du texte à l'écran.

Paramètres: - text (string) : Texte à afficher (peut inclure des variables) - x (number) : Position X du texte (coin gauche) - y (number) : Position Y du texte (baseline) - color (string) : Couleur du texte

Exemples:

drawText("Score: 1250", 10, 20, "#FFFFFF")
drawText("GAME OVER", 150, 150, "#FF0000")
drawText("Niveau " + currentLevel, 10, 40, "#FFFF00")
drawText("Vies: " + lives, 10, 60, "#00FF00")
drawText("Temps: " + timeRemaining, 300, 20, "#CYAN")

Cas d'Usage: - Interface utilisateur (score, vies, temps) - Messages de jeu (game over, level up) - Debug et informations développeur - Dialogues et instructions

Notes: - Police fixe : Arial 16px - Pas de retour à la ligne automatique - Concaténation avec + pour les variables

---

API Audio

Gestion des Sons

playSound(note, duration)

Joue une note musicale avec l'oscillateur intégré.

Paramètres: - note (string) : Nom de la note à jouer
- duration (number, optionnel) : Durée en secondes (défaut: 0.2)

Notes disponibles: - "do" : Do (C4 - 261.63 Hz) - "re" : Ré (D4 - 293.66 Hz) - "mi" : Mi (E4 - 329.63 Hz) - "fa" : Fa (F4 - 349.23 Hz) - "sol" : Sol (G4 - 392.00 Hz) - "la" : La (A4 - 440.00 Hz) - "si" : Si (B4 - 493.88 Hz) - "do2" : Do aigu (C5 - 523.25 Hz)

Exemples:

playSound("do")              // Note do, durée par défaut (0.2s)
playSound("mi", 0.5)         // Note mi pendant 0.5 secondes
playSound("sol", 0.1)        // Note sol courte pour effet

// Effets sonores de jeu
if isKeyPressed("space")
    playSound("do", 0.1)     // Son de tir
end

if collision
    playSound("si", 0.2)     // Son d'alerte
end

// Mélodie simple
playSound("do", 0.3)
playSound("re", 0.3)
playSound("mi", 0.3)

Cas d'Usage: - Effets sonores d'actions (saut, tir, collision) - Feedback audio pour l'interface - Mélodies et musiques simples - Sons d'ambiance et notifications

Notes techniques: - Sons générés par Web Audio API (oscillateur square wave) - Volume avec fade-out automatique pour éviter les clics - Nécessite une interaction utilisateur pour initialiser l'audio - Compatible avec tous les navigateurs modernes

---

API d'Entrées

Gestion du Clavier

isKeyPressed(keyName)

Vérifie si une touche est actuellement pressée.

Paramètres: - keyName (string) : Nom de la touche à vérifier

Valeur de retour: - boolean : true si pressée, false sinon

Touches supportées:

// Flèches directionnelles (et équivalents WASD)
isKeyPressed("up")        // ↑ ou W
isKeyPressed("down")      // ↓ ou S
isKeyPressed("left")      // ← ou A
isKeyPressed("right")     // → ou D

// Espace
isKeyPressed("space")     // Barre d'espace

Exemples:

// Mouvement basique
if isKeyPressed("left")
    playerX = playerX - speed
end
if isKeyPressed("right")
    playerX = playerX + speed
end

// Actions
if isKeyPressed("space")
    shoot()
end

// Contrôles combinés
if isKeyPressed("up") && isKeyPressed("space")
    jumpAndShoot()
end

Notes: - Détection en temps réel (pas d'événements) - Touches maintenues détectées chaque frame - Majuscules/minuscules importantes : "space" pas "Space"

---

Fonctions de Jeu

Fonctions Obligatoires

function start()

Fonction d'initialisation appelée une seule fois au démarrage du jeu.

Usage:

function start()
    // Initialisation des variables
    playerX = 200
    playerY = 150
    score = 0

    // Configuration initiale
    clearScreen("#000033")

    // Messages de démarrage
    drawText("Jeu initialisé!", 100, 100, "#FFFFFF")
end

Cas d'Usage: - Initialisation des variables de jeu - Positionnement initial des objets - Écran de démarrage - Configuration des paramètres

---

function update()

Boucle principale appelée 60 fois par seconde.

Usage:

function update()
    // 1. Effacer l'écran
    clearScreen("#000033")

    // 2. Traiter les entrées
    handleInput()

    // 3. Mettre à jour la logique
    updatePlayer()
    updateEnemies()

    // 4. Vérifier les collisions
    checkCollisions()

    // 5. Afficher les éléments
    drawGame()

    // 6. Interface utilisateur
    drawUI()
end

Structure recommandée: 1. Effacement : clearScreen() 2. Entrées : isKeyPressed() 3. Logique : Calculs et mises à jour 4. Collisions : Détections d'interaction 5. Rendu : Tous les draw...() 6. Interface : Score, vie, messages

---

Fonctions Personnalisées

Vous pouvez créer vos propres fonctions pour organiser votre code :

function updatePlayer()
    // Mouvement
    if isKeyPressed("left")
        playerX = playerX - playerSpeed
    end
    if isKeyPressed("right")
        playerX = playerX + playerSpeed
    end

    // Limites
    if playerX < 0
        playerX = 0
    end
    if playerX > 380
        playerX = 380
    end
end

function drawPlayer()
    drawRect(playerX, playerY, 20, 20, "#00FF00")

    if hasShield
        drawCircle(playerX + 10, playerY + 10, 25, "#0066FF")
    end
end

function resetGame()
    playerX = 200
    playerY = 150
    score = 0
    gameOver = false
end

Limitations importantes: - Pas de paramètres : function maFonction(param) ❌ - Pas de valeur de retour : return value ❌
- Accès variables globales : Toutes les variables sont partagées

---

Utilitaires

Calculs Mathématiques

Opérateurs disponibles :

// Arithmétique
let somme = a + b
let difference = a - b
let produit = a * b
let quotient = a / b
let modulo = a % b      // Reste de la division

// Comparaisons
a == b    // Égalité
a != b    // Différence
a < b     // Inférieur
a > b     // Supérieur
a <= b    // Inférieur ou égal
a >= b    // Supérieur ou égal

// Logique
a && b    // ET logique
a || b    // OU logique
!a        // NON logique

Fonctions Mathématiques Simulées

// Distance entre deux points (approximation)
let dx = x1 - x2
let dy = y1 - y2
let distance = (dx * dx) + (dy * dy)  // Distance au carré

// Valeur absolue
let abs = value < 0 ? -value : value

// Min/Max
let min = a < b ? a : b
let max = a > b ? a : b

// "Aléatoire" simple (pseudo-aléatoire)
let random = ((frameCount * 7) + (playerX * 3)) % 100

---

Constantes

Dimensions de l'Écran

// Taille du canvas
let SCREEN_WIDTH = 400
let SCREEN_HEIGHT = 300

// Limites utiles
let MAX_X = 380  // 400 - largeur objet (20)
let MAX_Y = 280  // 300 - hauteur objet (20)

Couleurs Prédéfinies

// Couleurs courantes (format hexadécimal recommandé)
let BLACK = "#000000"
let WHITE = "#FFFFFF"
let RED = "#FF0000"
let GREEN = "#00FF00"
let BLUE = "#0000FF"
let YELLOW = "#FFFF00"
let CYAN = "#00FFFF"
let MAGENTA = "#FF00FF"

// Couleurs de jeu typiques
let BACKGROUND = "#000033"
let PLAYER = "#00FF00"
let ENEMY = "#FF0000"
let UI_TEXT = "#FFFFFF"
let WARNING = "#FFFF00"

---

Exemples d'Usage

Interface Utilisateur Complète

let score = 0
let lives = 3
let level = 1
let time = 300

function drawUI()
    // Score en haut à gauche
    drawText("Score: " + score, 10, 20, "#FFFFFF")

    // Vies avec symboles
    drawText("Vies:", 10, 40, "#FFFFFF")
    for i = 1 to lives
        drawCircle(60 + (i * 15), 35, 5, "#FF0000")
    end

    // Niveau en haut à droite
    drawText("Niveau " + level, 320, 20, "#FFFF00")

    // Temps restant
    let minutes = time / 60
    let seconds = time % 60
    drawText("Temps: " + minutes + ":" + seconds, 300, 40, "#00FFFF")

    // Barre de santé
    drawRect(10, 270, 100, 10, "#660000")  // Fond
    drawRect(10, 270, playerHealth, 10, "#00FF00")  // Santé
    drawText("Santé", 120, 280, "#FFFFFF")
end

Système de Particules Simple

let particle1X = 0
let particle1Y = 0
let particle1Life = 0

let particle2X = 0
let particle2Y = 0
let particle2Life = 0

function createExplosion(x, y)
    particle1X = x
    particle1Y = y
    particle1Life = 30

    particle2X = x + 10
    particle2Y = y - 5
    particle2Life = 25
end

function updateParticles()
    if particle1Life > 0
        particle1Life = particle1Life - 1
        particle1Y = particle1Y - 2
    end

    if particle2Life > 0
        particle2Life = particle2Life - 1
        particle2Y = particle2Y - 1
        particle2X = particle2X + 1
    end
end

function drawParticles()
    if particle1Life > 0
        let alpha = particle1Life / 30
        if alpha > 0.5
            drawCircle(particle1X, particle1Y, 3, "#FFFF00")
        else
            drawCircle(particle1X, particle1Y, 2, "#FF6600")
        end
    end

    if particle2Life > 0
        drawCircle(particle2X, particle2Y, 2, "#FF0000")
    end
end

Détection de Collision Avancée

function checkRectCollision(x1, y1, w1, h1, x2, y2, w2, h2)
    // Collision AABB (Axis-Aligned Bounding Box)
    let collisionX = (x1 < x2 + w2) && (x1 + w1 > x2)
    let collisionY = (y1 < y2 + h2) && (y1 + h1 > y2)

    if collisionX && collisionY
        // Collision détectée
        return true
    end
    return false
end

function checkCircleCollision(x1, y1, r1, x2, y2, r2)
    let dx = x1 - x2
    let dy = y1 - y2
    let distance = (dx * dx) + (dy * dy)
    let radiusSum = (r1 + r2) * (r1 + r2)

    if distance < radiusSum
        return true
    end
    return false
end

function checkPointInRect(px, py, rx, ry, rw, rh)
    if (px >= rx) && (px <= rx + rw) && (py >= ry) && (py <= ry + rh)
        return true
    end
    return false
end

Animation et Tweening

let animTime = 0
let bounceHeight = 0

function updateAnimation()
    animTime = animTime + 1
    if animTime > 120
        animTime = 0
    end

    // Rebond sinusoïdal simplifié
    let phase = animTime / 60  // 0 à 2
    if phase < 1
        bounceHeight = phase * 50  // Monte
    else
        bounceHeight = (2 - phase) * 50  // Descend
    end
end

function drawAnimatedPlayer()
    let finalY = playerY - bounceHeight
    drawCircle(playerX, finalY, 15, "#00FF00")

    // Ombre au sol
    let shadowSize = 15 - (bounceHeight / 5)
    drawCircle(playerX, playerY + 20, shadowSize, "#333333")
end

Machine à États de Jeu

let gameState = "menu"  // "menu", "playing", "paused", "gameover"
let stateTime = 0

function update()
    stateTime = stateTime + 1

    if gameState == "menu"
        updateMenu()
    else if gameState == "playing"
        updatePlaying()
    else if gameState == "paused"
        updatePaused()
    else if gameState == "gameover"
        updateGameOver()
    end
end

function updateMenu()
    clearScreen("#000033")

    // Animation du titre
    let titleY = 100 + (stateTime / 10) % 20 - 10
    drawText("MON JEU GÉNIAL", 120, titleY, "#FFFF00")

    // Instructions clignotantes
    if (stateTime / 30) % 2 < 1
        drawText("Appuyez sur ESPACE", 120, 180, "#FFFFFF")
    end

    if isKeyPressed("space")
        gameState = "playing"
        stateTime = 0
        initGame()
    end
end

function updatePlaying()
    // Logique de jeu normale
    handleGameInput()
    updateGameLogic()
    drawGame()

    // Pause
    if isKeyPressed("space")
        gameState = "paused"
        stateTime = 0
    end
end

function updatePaused()
    // Redessiner le jeu en grisé/figé
    drawGame()

    // Overlay de pause
    drawRect(100, 100, 200, 100, "#000066")
    drawText("PAUSE", 170, 140, "#FFFFFF")
    drawText("ESPACE pour continuer", 110, 160, "#CCCCCC")

    if isKeyPressed("space")
        gameState = "playing"
        stateTime = 0
    end
end

---

⚡ Conseils de Performance

Optimisation du Rendu

// ✅ Bon : Un seul clearScreen par frame
function update()
    clearScreen("#000033")
    drawAllObjects()
    drawUI()
end

// ❌ Éviter : Multiples clearScreen
function update()
    clearScreen("#000033")
    drawPlayer()
    clearScreen("#000033")  // ❌ Inefficace
    drawEnemies()
end

Limitation des Calculs

// ✅ Calculer une fois, utiliser plusieurs fois
let playerCenterX = playerX + 10
let playerCenterY = playerY + 10

drawCircle(playerCenterX, playerCenterY, 15, "#00FF00")
checkCollision(playerCenterX, playerCenterY)

// ❌ Calculs répétitifs
drawCircle(playerX + 10, playerY + 10, 15, "#00FF00")
checkCollision(playerX + 10, playerY + 10)  // Recalcule

Gestion des Objets Multiples

// Technique pour simuler les tableaux sans support natif
let enemy1X = 100
let enemy1Y = 50
let enemy1Active = true

let enemy2X = 200
let enemy2Y = 50
let enemy2Active = true

function updateAllEnemies()
    if enemy1Active
        updateEnemy1()
    end
    if enemy2Active
        updateEnemy2()
    end
end

---

Cette API couvre toutes les fonctionnalités disponibles dans KodLab. Pour des exemples complets, consultez les Exemples de Jeux !

🚀 Bon développement avec KodLab !