02 · Sơ đồ lớp của các namespace OG.*

classDiagram
  class Scene {
    <<interface>>
    +enter(params, fromName)
    +exit(toName)
    +update(dt)
    +draw(ctx)
    +resume()
    +drawBelow : bool
  }
  class Scenes["OG.Scenes"] {
    -registry : name→Scene
    -stack : StackEntry[]
    +register(name, scene) Scene
    +get(name) Scene
    +has(name) bool
    +current() string
    +base() string
    +stackNames() string[]
    +go(name, params)
    +push(name, params)
    +pop()
    +update(dt)
    +draw(ctx)
  }
  class StackEntry {
    +name : string
    +scene : Scene
  }
  class level["scene 'level'"] {
    drawBelow mặc định
  }
  class boss["scene 'boss'"]
  class pause["scene 'pause'"] {
    drawBelow = true
  }
  class quiz["scene 'quiz'"] {
    drawBelow = true
    +choose(i)
    +finishPass()
    +later()
  }
  class comic["scene 'comic'"] {
    drawBelow = params.overlay
    +advance()
    +back()
    +finish(skipped)
  }
  class card["scene 'card'"] {
    drawBelow = true
    +close()
    +photo()
  }
  Scenes o-- StackEntry : stack
  StackEntry --> Scene
  level ..|> Scene
  boss ..|> Scene
  pause ..|> Scene
  quiz ..|> Scene
  comic ..|> Scene
  card ..|> Scene

classDiagram
  class Events["OG.Events"] {
    -listeners : name→fn[]
    +on(name, fn) Unsubscribe
    +off(name, fn)
    +once(name, fn) Unsubscribe
    +emit(name, payload)
    +clear(name)
  }
  class EV["OG.EV"] {
    <<constants>>
    +SCENE_CHANGE = 'scene:change'
    +PLAYER_JUMP = 'player:jump'
    +PAGE_COLLECT = 'page:collect'
    +... 60+ hằng
  }
  class Input["OG.Input"] {
    +keys : left,right,up,down,jump,action,pause,confirm,back,num1..3
    +pointer : x,y,down,justPressed,justReleased,inside
    -down : vừa nhấn trong frame
    -sources : 'phím:nguồn'→true
    +init(canvas)
    +pressed(k) bool
    +consume(k)
    +setKey(k, v)
    +reset()
    +endFrame()
    +bindTouch(root)
    +hasGesture() bool
  }
  class Loop["OG.Loop"] {
    +ctx
    +fps : EMA
    +start(ctx)
    +step(dt)
    -frame(t)
    -tick(dt)
  }
  class Camera["OG.Camera"] {
    +x, y : px thế giới
    +ox, oy : lệch do rung
    +reset()
    +follow(target, worldW)
    +shake(mag, dur)
    +update(dt)
    +apply(ctx)
    +toWorld(sx, sy) Vec2
  }
  class Physics["OG.Physics"] {
    +moveBody(body, dt, platforms, opts) MoveResult
    +aabb(a, b) bool
    +isStomp(body, prevBottom, target, tolerance) bool
  }
  class AABB {
    +x, y, w, h
  }
  class PhysicsBody {
    +vx, vy : px/giây
    +ground : bool
  }
  class MoveResult {
    +landed : bool
    +prevBottom : number
  }
  PhysicsBody --|> AABB
  Physics ..> PhysicsBody : sửa trực tiếp
  Physics ..> MoveResult : trả về
  Events ..> EV : tên chuẩn
  Input ..> Events : emit firstGesture, tap
  Loop --> Camera : update(dt)
  Loop ..> Input : endFrame() cuối frame

classDiagram
  class Game["OG.Game"] {
    +run : RunState
    +stage : StageStats
    +hud : HudState
    +newRun(opts) RunState
    +startLevel(idOrIndex)
    +beginStage(level)
    +tickTime(dt)
    +loseLife(cause) number
    +finishStage(levelId)
    +completeLevel(levelId) LevelResult
    +backToMap(params)
    +restartLevel()
    +retryRun()
    +gameOver()
    +victory()
  }
  class Level["OG.Level"] {
    +state : LevelState
    -hooks : LevelHook[] sắp theo order
    +addHook(hook)
    +removeHook(id)
    +hookIds()
    +drawWorld(ctx, st)
    +stompOk(p, prevBottom, target, tol, prevTop)
    +touchOk(p, box)
  }
  class LevelHook {
    <<interface>>
    +id : string
    +order : number
    +enter(st)
    +update(st, dt, player) bool
    +canExit(st, player) bool
    +drawWorld(ctx, st, t)
    +drawFront(ctx, st, t)
    +drawScreen(ctx, st, t)
  }
  class checkpoints["hook 'checkpoints' (10)"]
  class learn["hook 'learn' (20)"]
  class guide["hook 'guide' (30)"]
  class storyComics["hook 'story-comics' (40)"]
  class Player["OG.Player"] {
    +create(charId, x, y, mods, skinId) Player
    +update(p, dt, world) MoveResult
    +animState(p) string
    +hurt(p, cause) bool
    +draw(ctx, p, t)
  }
  class Enemies["OG.Enemies"] {
    +types : name→EnemyTypeDef
    +registerType(name, def)
    +create(src, index) Enemy
    +update(e, dt, world)
    +hurtbox(e) AABB
    +kill(e)
  }
  class EnemyTypeDef {
    <<interface>>
    +w, h, score, stompable
    +init(e, src)
    +update(e, dt, world)
    +draw(ctx, e, t)
  }
  class Difficulty["OG.Difficulty"] {
    +MODES : kid, challenge
    +ASSIST : 1, 2
    +mode() string
    +set(m)
    +params(levelId) Object
    +get(key, levelId)
    +startLives()
    +scaleEnemy(e)
    +setupBoss(boss, arena)
    +bossTimeScale()
    +onFall(p, world) bool
    +softFail(info) bool
    +recordFail(levelId)
  }
  Level o-- LevelHook : hooks
  checkpoints ..|> LevelHook
  learn ..|> LevelHook
  guide ..|> LevelHook
  storyComics ..|> LevelHook
  Enemies o-- EnemyTypeDef : registry
  Level ..> Player
  Level ..> Enemies
  Level ..> Game : finishStage
  Game ..> Difficulty : util.call softFail
  Player ..> Difficulty : coyoteTime, hurtInvuln

classDiagram
  class Bosses["OG.Bosses"] {
    -defs : id→BossDef
    +factories : id→fn(arena, cfg)
    +kit : K
    +init()
    +register(def)
    +has(id) bool
    +list() string[]
    +getInfo(id)
    +getArena(id)
    +create(id, arena) BossInstance
  }
  class Kit["OG.Bosses.kit (K)"] {
    +createBase(spec, arena, cfg) BossInstance
    +spawnProj(b, p)
    +updateProjectiles(b, dt, arena)
    +diffOf(arena) BossDifficulty
    +drawTelegraph(ctx, b, t, k)
    +drawWarnZone(...)
    +drawStompHint(ctx, x, y, t)
    +normalizeArena(arena)
  }
  class BossInstance {
    +id, name, hp, maxHp, phase
    +state : string
    +stateT, stateDur : giây
    +patterns : phase→action[]
    +update(dt, arena)
    +draw(ctx, arena)
    +setState(s, dur)
    +stateDone() bool
    +choose(arena)
    +onHit(dmg, arena) bool
    +getWeakspot() AABB
    +getHurtboxes() AABB[]
    +isDefeated() bool
  }
  class BossHooks {
    <<interface>>
    +startAction(a, arena)
    +think(dt, arena)
    +isVulnerable() bool
    +isFullHurt() bool
    +onHurt(arena)
    +drawBehind(ctx, arena, t)
    +drawFront(ctx, arena, t)
  }
  class DeeDee["deedee.js"] {
    SPEC phaseAt [3, 1]
  }
  class Joey["joey.js"] {
    SPEC 3 pha
  }
  class Marky["marky.js"] {
    SPEC 3 pha
  }
  class Trio["trio.js (composite)"] {
    -members : BossInstance[3]
    -ctrl : BossTurnCtrl
    +syncHp()
    +onHit(dmg, arena, member)
    +isDefeated() bool
  }
  class BossTurnCtrl {
    +request(member) bool
    +release(member)
  }
  class Arena {
    +levelId, bossId, theme, width, floorY
    +player : Player
    +enemies : Enemy[]
    +difficulty : Object
    +hurtPlayer(cause)
    +overlapsPlayer(rect) bool
    +shake(mag, dur)
    +emit(name, payload)
    +addScore(n)
    +spawnEnemy(src)
  }
  Bosses *-- Kit
  Kit ..> BossInstance : tạo khung
  BossInstance ..> BossHooks : gọi nếu có
  DeeDee ..|> BossHooks
  Joey ..|> BossHooks
  Marky ..|> BossHooks
  Trio o-- BossInstance : 3 thành viên
  Trio *-- BossTurnCtrl
  BossInstance --> Arena : nhận qua tham số

classDiagram
  class Sprites["OG.Sprites (sprites.js)"] {
    -cache : enabled, map: Map, hits, misses, px
    -CACHE_MAX = 320 khung
    -CACHE_MAX_PX = 16 triệu điểm ảnh
    +drawCharacter(ctx, charId, animState, t, opts)
    +getAnimStates() string[]
    +drawPortrait(ctx, charId, x, y, size, opts)
    +setCacheEnabled(on)
    +setCacheLimit(...)
    +clearCache()
    +cacheStats()
    -normState(s) string
    -quantize(state, t, kind) QuantizedTime
    -cacheGet(key) CachedFrame
    -cachePut(key, frame)
  }
  class CachedFrame {
    +cv : canvas phụ
    +ox, oy : vị trí chân
    +w, h
    +px : số điểm ảnh
  }
  class SceneryGfx["OG.Sprites (scenery.js)"] {
    +drawBackground(ctx, theme, camX, t)
    +drawPlatform(ctx, plat, theme, t)
    +drawDecor(ctx, theme, worldW, t)
    +drawOverlay(ctx, theme, camX, t)
    +drawProp(ctx, id, x, y, t, opts) bool
    +resolveTheme(id) ResolvedTheme
  }
  class Scenery["OG.Scenery (core)"] {
    -themes : id→ThemeDef
    -decors : kind→DecorFn
    -layers : kind→LayerFn
    +BUILTIN
    +registerTheme(id, def)
    +getTheme(id)
    +baseOf(id)
    +registerDecor(kind, fn)
    +drawDecor(ctx, kind, x, y, scale, t, opts) bool
    +registerLayer(kind, fn)
    +drawLayer(ctx, layer, camX, t, theme)
    +fallbackDecor
    +fallbackLayer
  }
  class Decor["OG.Decor (decor.js)"] {
    -SPRITE_MAX = 96, TILE_MAX = 28
    +define(kind, fn)
    +registerTiled(kind, spec)
    +sprite(...)
    +drawSprite(...)
    +cacheStats()
    -remember(store, order, max, key, val) FIFO
  }
  Sprites *-- CachedFrame : Map LRU
  SceneryGfx ..> Scenery : đọc ThemeDef, gọi drawLayer, drawDecor
  Decor ..> Scenery : define đăng ký vào registry

classDiagram
  class Audio["OG.Audio (audio.js)"] {
    -ctx : AudioContext hoặc null
    -master, musicBus, sfxBus, compressor : GainNode
    -noiseBuf : 1 giây nhiễu trắng
    -unlocked : bool
    -duck : hệ số giảm nhạc
    +currentTrack : string
    +tracks : id→TrackDef
    +init()
    +unlock() bool
    +isReady() bool
    +playMusic(trackId)
    +stopMusic(fade)
    +sfx(name, opts)
    +setVolume(ch, v)
    +mute(on)
    +toggleMute()
    +setDuck(v)
    -createContext()
    -playSfx(name, opts)
    -tone(ToneOpts)
    -noise(NoiseOpts)
    -applyVolumes()
    -bindEvents()
  }
  class Engine["OG.Audio._engine"] {
    tone, noise, mtof...
  }
  class Music["OG.Audio._music (music.js)"] {
    -compiled : id→CompiledSong
    -cur : MusicVoice
    -LOOKAHEAD = 0.15 giây
    +play(id)
    +stop(fade)
    +resolve(id)
    +list()
    +isPlaying(id)
    -compile(id) CompiledSong
    -tick()
    -playEvent(ev, t, song, bus)
  }
  class TrackDef {
    +bpm, loop, swing
    +extend : id bản gốc
    +transpose
    +lead, bass
  }
  class CompiledSong {
    +id
    +steps : SongEvent[][]
    +total
    +stepDur : giây
  }
  class MusicVoice {
    +song : CompiledSong
    +gain : GainNode
    +step
    +nextTime : giây AudioContext
  }
  Audio *-- Engine
  Audio *-- Music : gắn vào lúc load music.js
  Music ..> Engine : dùng tone/noise
  Music o-- TrackDef : tracks
  Music ..> CompiledSong : compile + cache
  Music *-- MusicVoice : bản đang phát

classDiagram
  class Story["OG.Story"] {
    +init()
    +current() jid
    +startJourney(jid, opts) bool
    +playLevel(levelId) bool
    +afterLevel(result) bool
    +finishJourney(jid)
    +playComic(jid, comicId, opts)
    +playComics(jid, list, opts)
    +pushComic(jid, comicId, onDone)
    +hasSeen(jid, comicId) bool
    +markSeen(jid, comicId)
    +onSoftFail(info) bool
    +ui : font, wrap, drawBubble, drawButton, hit, fx...
    -goNext(next)
  }
  class StoryNextStep {
    +scene
    +params
    +start : bool
    +fn : Function
  }
  class Learn["OG.Learn"] {
    +hasCard(jid, cardId) bool
    +unlockCard(jid, cardId, opts) bool
    +listCards(jid, areaId)
    +count(jid, areaId)
    +whereIs(jid, cardId)
    +openCard(jid, cardId, opts)
    +openNotebook(jid, back, backParams)
    +isQuizPassed(jid, quizId) bool
    +openQuiz(jid, quizId, opts)
    +answerQuiz(jid, quizId, choice, ctx) AnswerResult
    +drawIcon(ctx, icon, x, y, size, t)
    -learnHook : LevelHook
    -openGate(st, g)
  }
  class Guide["OG.Guide"] {
    +init()
    +guideOf(jid)
    +say(text, seconds) bool
    +talk(st, spot)
    +drawSay(ctx)
  }
  class Photos["OG.Photos"] {
    -registry : jid→cardId→PhotoEntry
    -cache : 'jid/cardId'→PhotoRecord
    +licenseOk(name) bool
    +register(jid, map)
    +get(jid, cardId) PhotoEntry
    +image(jid, cardId) PhotoRecord
    +ready(jid, cardId) img
    +loading(jid, cardId) bool
    +preload(jid, cardIds)
    +creditLine(e, maxAuthor)
    +drawCover(...)
    +drawShimmer(...)
  }
  class Journeys["OG.Journeys (core)"] {
    +register(def)
    +getLevel(id)
    +getCard(jid, id)
    +getQuiz(jid, id)
    +getComic(jid, id)
    +validate(idOrDef)
  }
  Story ..> StoryNextStep : continuation dạng dữ liệu
  Story ..> Journeys
  Learn ..> Journeys
  Learn ..> Photos : preload
  Guide ..> Learn : unlockCard (spot.card)
  Story ..> Learn

classDiagram
  class Save["OG.Save"] {
    +data : SaveData
    +available : bool
    -KEY = 'oggyAdventure.save.v1'
    -LEGACY_BEST_KEY = 'oggyBest'
    +load() SaveData
    +commit() bool
    +get(path, fallback)
    +set(path, value)
    +ns(name) Object
    +addCoins(n, reason)
    +spendCoins(n, reason) bool
    +setSetting(key, value)
    +reset()
    -defaults() SaveData
    -merge(base, saved)
  }
  class Social["OG.Social"] {
    +mountResult(panelEl, result)
    +share(result) Promise~bool~
    +createCard(result) canvas
    +cardDataURL(result)
    +cardBlob(result) Blob
    +copyText(text) Promise
    +submitResult(result, name)
    +submitScore(entry) rank
    +getLeaderboard(limit)
    +backend : LeaderboardBackend
    +backends : id→LeaderboardBackend
    +registerBackend(b)
    +setBackend(idOrBackend)
    +createHttpBackend(opts)
    +useOnline(url, opts)
  }
  class LeaderboardBackend {
    <<interface>>
    +id
    +name
    +online : bool
    +submit(entry) Promise
    +list(limit) Promise
    +clear() Promise
  }
  class local["backends.local"] {
    +submitSync(entry) rank
    +listSync(limit)
  }
  class http["createHttpBackend(...)"] {
    +url
    GET url/scores
    POST url/scores
  }
  Social o-- LeaderboardBackend : backends
  local ..|> LeaderboardBackend
  http ..|> LeaderboardBackend
  local ..> Save : ns('social').leaderboard
  Social ..> Save : playerName