@nice2dev/game-engine 1.0.4 → 1.0.10

package/dist/cjs/export/Pico8Exporter.js

@@ -0,0 +1,846 @@
+'use strict';
+
+var PlatformExporter = require('./PlatformExporter.js');
+
+/* ────────────────────────────────────────────────────────────────
+   PICO-8 Exporter — Fantasy Console Export
+   
+   Exports Nice2Dev projects to PICO-8 format:
+   - P8 cartridge file format
+   - Lua code section
+   - Graphics data (sprites, map)
+   - Sound effects
+   - Music patterns
+   
+   Constraints:
+   - 128x128 pixels
+   - 16 colors palette
+   - 8192 tokens max
+   - 32KB cartridge size
+──────────────────────────────────────────────────────────────── */
+/* ── PICO-8 Constants ─────────────────────────────────────────── */
+const PICO8_PALETTE = [
+    '#000000', // 0 - black
+    '#1D2B53', // 1 - dark blue
+    '#7E2553', // 2 - dark purple
+    '#008751', // 3 - dark green
+    '#AB5236', // 4 - brown
+    '#5F574F', // 5 - dark gray
+    '#C2C3C7', // 6 - light gray
+    '#FFF1E8', // 7 - white
+    '#FF004D', // 8 - red
+    '#FFA300', // 9 - orange
+    '#FFEC27', // 10 - yellow
+    '#00E436', // 11 - green
+    '#29ADFF', // 12 - blue
+    '#83769C', // 13 - indigo
+    '#FF77A8', // 14 - pink
+    '#FFCCAA', // 15 - peach
+];
+/* ── Exporter Implementation ──────────────────────────────────── */
+class Pico8Exporter extends PlatformExporter.PlatformExporter {
+    constructor() {
+        super(...arguments);
+        this.platformId = 'pico8';
+        this.platformInfo = {
+            id: 'pico8',
+            name: 'PICO-8',
+            description: 'PICO-8 Fantasy Console - Retro game development platform',
+            website: 'https://www.lexaloffle.com/pico-8.php',
+            features: ['2d-rendering', 'pixel-graphics', 'audio', 'music', 'retro'],
+            supportedAssets: ['sprite', 'tilemap', 'audio', 'music'],
+            exportFormats: ['.p8'],
+        };
+    }
+    async doExport(project, options) {
+        options.platformOptions ?? {};
+        // Generate main P8 cartridge
+        await this.generateCartridge(project, options);
+        // Generate standalone Lua for reference
+        await this.generateLuaSource(project, options);
+        // Generate README
+        await this.generateReadme(project, options);
+    }
+    /* ── Cartridge Generation ───────────────────────────────────── */
+    async generateCartridge(project, options) {
+        options.platformOptions ?? {};
+        const safeName = (options.projectName ?? project.name)
+            .toLowerCase()
+            .replace(/[^a-z0-9_]/g, '_');
+        // Generate code section
+        const code = this.generateCode(project, options);
+        // Generate graphics section (placeholder)
+        const gfx = this.generateGfxSection(project, options);
+        // Generate gff (sprite flags) section
+        const gff = this.generateGffSection(project);
+        // Generate map section
+        const map = this.generateMapSection(project);
+        // Generate sfx section
+        const sfx = this.generateSfxSection(project, options);
+        // Generate music section
+        const music = this.generateMusicSection(project, options);
+        // Assemble cartridge
+        const cartridge = `pico-8 cartridge // http://www.pico-8.com
+version 41
+__lua__
+${code}
+__gfx__
+${gfx}
+__gff__
+${gff}
+__map__
+${map}
+__sfx__
+${sfx}
+__music__
+${music}
+`;
+        this.addTextFile(`${safeName}.p8`, cartridge);
+    }
+    /* ── Code Generation ────────────────────────────────────────── */
+    generateCode(project, options) {
+        const platformOpts = options.platformOptions ?? {};
+        const optimizeTokens = platformOpts.optimizeTokens ?? false;
+        const lines = [];
+        // Header comment
+        lines.push(`-- ${project.name} v${project.version}`);
+        lines.push('-- generated from nice2dev');
+        lines.push('');
+        // Game state
+        lines.push('-- game state');
+        lines.push('game={');
+        lines.push('  state="play",');
+        lines.push('  frame=0,');
+        lines.push('  cam={x=0,y=0},');
+        lines.push('  entities={},');
+        lines.push('  debug=' + (platformOpts.includeDebug ? 'true' : 'false'));
+        lines.push('}');
+        lines.push('');
+        // Core functions
+        lines.push(this.generateCoreFunctions(project, options));
+        // Entity system
+        lines.push(this.generateEntitySystem(project, options));
+        // Entity definitions
+        lines.push(this.generateEntityDefinitions(project, options));
+        // Scene setup
+        lines.push(this.generateSceneSetup(project, options));
+        // Utility functions
+        lines.push(this.generateUtilityFunctions(optimizeTokens));
+        // Debug overlay
+        if (platformOpts.includeDebug) {
+            lines.push(this.generateDebugOverlay());
+        }
+        return lines.join('\n');
+    }
+    generateCoreFunctions(project, options) {
+        return `
+-- initialization
+function _init()
+  -- setup palette
+  palt(0,false)
+  palt(14,true) -- pink as transparent
+  
+  -- initialize game
+  game.frame=0
+  game.entities={}
+  
+  -- load first scene
+  load_scene(1)
+end
+
+-- update (60fps)
+function _update60()
+  if game.state=="play" then
+    game.frame+=1
+    
+    -- update all entities
+    for e in all(game.entities) do
+      if e.update then
+        e:update()
+      end
+    end
+    
+    -- handle collisions
+    check_collisions()
+    
+    -- clean dead entities
+    for i=#game.entities,1,-1 do
+      if game.entities[i].dead then
+        del(game.entities,game.entities[i])
+      end
+    end
+  end
+end
+
+-- draw
+function _draw()
+  cls(${this.getClosestPico8Color(project.scenes[0]?.background ?? '#000000')})
+  
+  -- apply camera
+  camera(game.cam.x,game.cam.y)
+  
+  -- draw map
+  map(0,0,0,0,128,64)
+  
+  -- draw entities (sorted by y)
+  sort_entities()
+  for e in all(game.entities) do
+    if e.draw then
+      e:draw()
+    end
+  end
+  
+  camera()
+  
+  -- ui
+  draw_ui()
+  
+  -- debug
+  if game.debug then
+    draw_debug()
+  end
+end
+`;
+    }
+    generateEntitySystem(project, options) {
+        return `
+-- entity system
+function make_entity(type,x,y,props)
+  local e={
+    type=type,
+    x=x,
+    y=y,
+    dx=0,
+    dy=0,
+    w=8,
+    h=8,
+    spr=0,
+    flip_x=false,
+    anim={frames={0},speed=0.1,t=0,i=1},
+    dead=false,
+    tags={}
+  }
+  -- apply props
+  if props then
+    for k,v in pairs(props) do
+      e[k]=v
+    end
+  end
+  -- type-specific init
+  if entity_types[type] then
+    for k,v in pairs(entity_types[type]) do
+      if type(v)!="function" then
+        e[k]=v
+      else
+        e[k]=v
+      end
+    end
+    if entity_types[type].init then
+      entity_types[type].init(e)
+    end
+  end
+  add(game.entities,e)
+  return e
+end
+
+function kill_entity(e)
+  e.dead=true
+end
+
+function has_tag(e,tag)
+  for t in all(e.tags) do
+    if t==tag then return true end
+  end
+  return false
+end
+
+-- collision
+function check_collisions()
+  for i=1,#game.entities do
+    local a=game.entities[i]
+    if not a.dead and a.solid then
+      for j=i+1,#game.entities do
+        local b=game.entities[j]
+        if not b.dead and b.solid then
+          if collides(a,b) then
+            if a.on_collision then a:on_collision(b) end
+            if b.on_collision then b:on_collision(a) end
+          end
+        end
+      end
+    end
+  end
+end
+
+function collides(a,b)
+  return a.x<b.x+b.w and
+         a.x+a.w>b.x and
+         a.y<b.y+b.h and
+         a.y+a.h>b.y
+end
+`;
+    }
+    generateEntityDefinitions(project, options) {
+        const lines = [];
+        lines.push('');
+        lines.push('-- entity types');
+        lines.push('entity_types={}');
+        lines.push('');
+        // Generate entity types from prefabs and entities
+        const entityTypes = new Map();
+        for (const prefab of project.prefabs) {
+            entityTypes.set(prefab.name.toLowerCase().replace(/[^a-z0-9_]/g, '_'), prefab.entity);
+        }
+        for (const scene of project.scenes) {
+            for (const entity of scene.entities) {
+                const typeName = (entity.name ?? entity.id).toLowerCase().replace(/[^a-z0-9_]/g, '_');
+                if (!entityTypes.has(typeName)) {
+                    entityTypes.set(typeName, entity);
+                }
+            }
+        }
+        for (const [typeName, entity] of entityTypes) {
+            lines.push(this.entityTypeToLua(typeName, entity));
+        }
+        return lines.join('\n');
+    }
+    entityTypeToLua(typeName, entity) {
+        const tags = entity.tags ?? [];
+        entity.components.some((c) => c.type === 'sprite');
+        const hasPhysics = entity.components.some((c) => c.type === 'rigidbody');
+        entity.components.some((c) => c.type === 'script');
+        const sprIndex = this.getEntitySpriteIndex(entity);
+        const speed = this.getComponentProperty(entity, 'movement', 'speed', 1);
+        return `entity_types.${typeName}={
+  spr=${sprIndex},
+  w=8,h=8,
+  solid=${hasPhysics},
+  tags={${tags.map((t) => `"${t}"`).join(',')}},
+  speed=${speed / 50},
+  hp=${this.getComponentProperty(entity, 'health', 'max', 3)},
+  max_hp=${this.getComponentProperty(entity, 'health', 'max', 3)},
+  
+  init=function(self)
+    -- custom init
+  end,
+  
+  update=function(self)
+    -- movement
+    self.x+=self.dx
+    self.y+=self.dy
+    
+    -- friction
+    self.dx*=0.9
+    self.dy*=0.9
+    
+    -- animation
+    if self.anim.speed>0 then
+      self.anim.t+=self.anim.speed
+      if self.anim.t>=1 then
+        self.anim.t=0
+        self.anim.i+=1
+        if self.anim.i>#self.anim.frames then
+          self.anim.i=1
+        end
+        self.spr=self.anim.frames[self.anim.i]
+      end
+    end
+  end,
+  
+  draw=function(self)
+    spr(self.spr,self.x,self.y,1,1,self.flip_x)
+  end,
+  
+  on_collision=function(self,other)
+    -- handle collision
+  end,
+  
+  hurt=function(self,dmg)
+    self.hp-=(dmg or 1)
+    if self.hp<=0 then
+      self:die()
+    end
+  end,
+  
+  die=function(self)
+    -- spawn particles
+    for i=1,4 do
+      spawn_particle(self.x+4,self.y+4,7)
+    end
+    kill_entity(self)
+  end
+}
+
+`;
+    }
+    getEntitySpriteIndex(entity) {
+        // Map entity types to sprite indices (placeholder logic)
+        const name = (entity.name ?? 'entity').toLowerCase();
+        if (name.includes('player')) {
+            return 1;
+        }
+        if (name.includes('enemy')) {
+            return 16;
+        }
+        if (name.includes('item')) {
+            return 32;
+        }
+        if (name.includes('bullet') || name.includes('projectile')) {
+            return 48;
+        }
+        return 0;
+    }
+    getComponentProperty(entity, componentType, property, defaultValue) {
+        const comp = entity.components.find((c) => c.type === componentType);
+        if (comp && comp.properties && property in comp.properties) {
+            return comp.properties[property];
+        }
+        return defaultValue;
+    }
+    generateSceneSetup(project, options) {
+        const lines = [];
+        lines.push('');
+        lines.push('-- scenes');
+        lines.push('scenes={}');
+        lines.push('');
+        for (let i = 0; i < project.scenes.length; i++) {
+            const scene = project.scenes[i];
+            const sceneName = scene.name.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+            lines.push(`scenes[${i + 1}]={`);
+            lines.push(`  name="${sceneName}",`);
+            lines.push(`  entities={`);
+            for (const entity of scene.entities) {
+                const typeName = (entity.name ?? entity.id).toLowerCase().replace(/[^a-z0-9_]/g, '_');
+                const pos = entity.position ?? { x: 0, y: 0 };
+                // Scale position for PICO-8 (128x128)
+                const x = Math.floor((pos.x / project.settings.resolution.width) * 128);
+                const y = Math.floor((pos.y / project.settings.resolution.height) * 128);
+                lines.push(`    {type="${typeName}",x=${x},y=${y}},`);
+            }
+            lines.push(`  }`);
+            lines.push(`}`);
+            lines.push('');
+        }
+        lines.push('function load_scene(n)');
+        lines.push('  game.entities={}');
+        lines.push('  local s=scenes[n]');
+        lines.push('  if s then');
+        lines.push('    for e in all(s.entities) do');
+        lines.push('      make_entity(e.type,e.x,e.y)');
+        lines.push('    end');
+        lines.push('  end');
+        lines.push('end');
+        return lines.join('\n');
+    }
+    generateUtilityFunctions(optimizeTokens) {
+        if (optimizeTokens) {
+            return `
+-- utils (optimized)
+function v(x,y) return {x=x,y=y} end
+function dist(a,b) return sqrt((b.x-a.x)^2+(b.y-a.y)^2) end
+function lerp(a,b,t) return a+(b-a)*t end
+function clamp(v,mn,mx) return max(mn,min(mx,v)) end
+function rnd_range(a,b) return a+rnd(b-a) end
+function sign(v) return v>0 and 1 or v<0 and -1 or 0 end
+
+function sort_entities()
+  for i=1,#game.entities do
+    local j=i
+    while j>1 and game.entities[j-1].y>game.entities[j].y do
+      game.entities[j],game.entities[j-1]=game.entities[j-1],game.entities[j]
+      j-=1
+    end
+  end
+end
+
+function spawn_particle(x,y,c)
+  local p={x=x,y=y,dx=rnd(2)-1,dy=rnd(2)-1,c=c,life=15+rnd(10),draw=function(s) pset(s.x,s.y,s.c) end,update=function(s) s.x+=s.dx s.y+=s.dy s.life-=1 if s.life<=0 then s.dead=true end end}
+  add(game.entities,p)
+end
+
+function draw_ui()
+  -- hud here
+end
+`;
+        }
+        return `
+-- utility functions
+function vec(x,y)
+  return {x=x,y=y}
+end
+
+function dist(a,b)
+  local dx=b.x-a.x
+  local dy=b.y-a.y
+  return sqrt(dx*dx+dy*dy)
+end
+
+function lerp(a,b,t)
+  return a+(b-a)*t
+end
+
+function clamp(val,min_val,max_val)
+  return max(min_val,min(max_val,val))
+end
+
+function rnd_range(min_val,max_val)
+  return min_val+rnd(max_val-min_val)
+end
+
+function sign(val)
+  if val>0 then return 1 end
+  if val<0 then return -1 end
+  return 0
+end
+
+function sort_entities()
+  -- insertion sort by y
+  for i=1,#game.entities do
+    local j=i
+    while j>1 and game.entities[j-1].y>game.entities[j].y do
+      game.entities[j],game.entities[j-1]=game.entities[j-1],game.entities[j]
+      j-=1
+    end
+  end
+end
+
+function spawn_particle(x,y,color)
+  local p={
+    x=x,
+    y=y,
+    dx=rnd(2)-1,
+    dy=rnd(2)-1,
+    c=color,
+    life=15+rnd(10),
+    dead=false,
+    draw=function(self)
+      pset(self.x,self.y,self.c)
+    end,
+    update=function(self)
+      self.x+=self.dx
+      self.y+=self.dy
+      self.dy+=0.05 -- gravity
+      self.life-=1
+      if self.life<=0 then
+        self.dead=true
+      end
+    end
+  }
+  add(game.entities,p)
+end
+
+function screensh()
+  -- screenshake
+  if game.shake and game.shake>0 then
+    game.cam.x=rnd(game.shake)-game.shake/2
+    game.cam.y=rnd(game.shake)-game.shake/2
+    game.shake-=0.5
+  else
+    game.shake=0
+    game.cam.x=0
+    game.cam.y=0
+  end
+end
+
+function shake(amount)
+  game.shake=(game.shake or 0)+amount
+end
+
+function draw_ui()
+  -- hud
+  print("nice2dev",1,1,7)
+end
+
+-- input helpers
+function btn_pressed(b)
+  return btn(b) and not btnp(b)
+end
+`;
+    }
+    generateDebugOverlay() {
+        return `
+-- debug overlay
+function draw_debug()
+  local mem=flr(stat(0)/1024*100)/100
+  local cpu=flr(stat(1)*100)
+  
+  rectfill(0,0,127,12,0)
+  print("fps:"..stat(7).." cpu:"..cpu.."%",1,1,7)
+  print("mem:"..mem.."kb ent:"..#game.entities,1,7,7)
+  
+  -- draw hitboxes
+  for e in all(game.entities) do
+    if e.solid then
+      rect(e.x,e.y,e.x+e.w-1,e.y+e.h-1,8)
+    end
+  end
+end
+`;
+    }
+    /* ── Data Sections ──────────────────────────────────────────── */
+    generateGfxSection(project, options) {
+        // Generate placeholder sprite sheet (128x128 = 256 lines of 128 hex chars)
+        // Each pixel is 4 bits (one hex char)
+        const lines = [];
+        // Basic placeholder sprites
+        // Sprite 0: Empty
+        // Sprite 1: Player placeholder (simple face)
+        // Sprite 16: Enemy placeholder
+        // Sprite 32: Item placeholder
+        for (let row = 0; row < 128; row++) {
+            let line = '';
+            for (let col = 0; col < 128; col++) {
+                const spriteX = col % 8;
+                const spriteY = row % 8;
+                const spriteIndex = Math.floor(col / 8) + Math.floor(row / 8) * 16;
+                let pixel = 0;
+                // Sprite 1: Player (simple character)
+                if (spriteIndex === 1) {
+                    // Draw a simple face
+                    if (spriteY === 1 && (spriteX === 2 || spriteX === 5)) {
+                        pixel = 12;
+                    } // eyes (blue)
+                    else if (spriteY === 3 && spriteX >= 2 && spriteX <= 5) {
+                        pixel = 8;
+                    } // mouth (red)
+                    else if (spriteY >= 1 && spriteY <= 5 && spriteX >= 1 && spriteX <= 6) {
+                        pixel = 15;
+                    } // face (peach)
+                    else if ((spriteY === 0 || spriteY === 6) && spriteX >= 2 && spriteX <= 5) {
+                        pixel = 4;
+                    } // hair
+                    else if ((spriteX === 0 || spriteX === 7) && spriteY >= 1 && spriteY <= 5) {
+                        pixel = 4;
+                    } // hair sides
+                }
+                // Sprite 16: Enemy (red square)
+                else if (spriteIndex === 16) {
+                    if (spriteX >= 1 && spriteX <= 6 && spriteY >= 1 && spriteY <= 6) {
+                        pixel = 8;
+                    } // red body
+                    if (spriteY === 2 && (spriteX === 2 || spriteX === 5)) {
+                        pixel = 7;
+                    } // eyes
+                }
+                // Sprite 32: Item (yellow coin)
+                else if (spriteIndex === 32) {
+                    if (spriteX >= 2 && spriteX <= 5 && spriteY >= 1 && spriteY <= 6) {
+                        pixel = 10;
+                    } // yellow
+                    if (spriteY >= 2 && spriteY <= 5 && (spriteX === 1 || spriteX === 6)) {
+                        pixel = 10;
+                    }
+                    if (spriteX >= 3 && spriteX <= 4 && spriteY >= 3 && spriteY <= 4) {
+                        pixel = 9;
+                    } // orange center
+                }
+                line += pixel.toString(16);
+            }
+            lines.push(line);
+        }
+        return lines.join('\n');
+    }
+    generateGffSection(project) {
+        // Sprite flags: 256 bytes (2 per line, 128 lines)
+        // All zeros for placeholder
+        const lines = [];
+        for (let i = 0; i < 2; i++) {
+            lines.push('0'.repeat(256));
+        }
+        return lines.join('\n');
+    }
+    generateMapSection(project) {
+        // Map: 128x64 tiles, stored as 128 bytes per row, 64 rows
+        // Actually stored as 128x32 in __map__ section
+        const lines = [];
+        for (let i = 0; i < 32; i++) {
+            lines.push('0'.repeat(256));
+        }
+        return lines.join('\n');
+    }
+    generateSfxSection(project, options) {
+        const platformOpts = options.platformOptions ?? {};
+        if (!platformOpts.sfxPlaceholders) {
+            // Empty sfx section
+            return '';
+        }
+        // Placeholder sound effects
+        const lines = [];
+        // SFX 0: Jump sound
+        lines.push('000100000c0500c0500b0500a050090500805007050060500505004050030500205001050000500005000050000500005000050000500005000050000500005');
+        // SFX 1: Hit sound
+        lines.push('001000001805018050170501605015050140501305012050110501005010050100500005000050000500005000050000500005000050000500005000050');
+        // SFX 2: Pickup sound
+        lines.push('000600002405024050260502805030050320503305034050350503605036050350503405033050300502705024050000500005000050000500005000050');
+        // Fill rest with empty
+        for (let i = 3; i < 64; i++) {
+            lines.push('001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000');
+        }
+        return lines.join('\n');
+    }
+    generateMusicSection(project, options) {
+        const platformOpts = options.platformOptions ?? {};
+        if (!platformOpts.musicPatterns) {
+            return '';
+        }
+        // Placeholder music patterns
+        const lines = [];
+        // Pattern 0: Simple loop
+        lines.push('00 41424344');
+        // Fill rest with empty
+        for (let i = 1; i < 64; i++) {
+            lines.push('00 41424344'.replace(/\d/g, '4'));
+        }
+        return lines.join('\n');
+    }
+    /* ── Lua Source ─────────────────────────────────────────────── */
+    async generateLuaSource(project, options) {
+        const code = this.generateCode(project, options);
+        this.addTextFile('source.lua', `-- ${project.name} - Source Code\n-- For reference only (use .p8 file in PICO-8)\n\n${code}`);
+    }
+    /* ── Color Utilities ────────────────────────────────────────── */
+    getClosestPico8Color(hex) {
+        const cleanHex = hex.replace('#', '').toLowerCase();
+        const r = parseInt(cleanHex.substring(0, 2), 16);
+        const g = parseInt(cleanHex.substring(2, 4), 16);
+        const b = parseInt(cleanHex.substring(4, 6), 16);
+        let closestIndex = 0;
+        let closestDist = Infinity;
+        for (let i = 0; i < PICO8_PALETTE.length; i++) {
+            const palHex = PICO8_PALETTE[i].replace('#', '');
+            const pr = parseInt(palHex.substring(0, 2), 16);
+            const pg = parseInt(palHex.substring(2, 4), 16);
+            const pb = parseInt(palHex.substring(4, 6), 16);
+            const dist = Math.sqrt(Math.pow(r - pr, 2) + Math.pow(g - pg, 2) + Math.pow(b - pb, 2));
+            if (dist < closestDist) {
+                closestDist = dist;
+                closestIndex = i;
+            }
+        }
+        return closestIndex;
+    }
+    /* ── README ─────────────────────────────────────────────────── */
+    async generateReadme(project, options) {
+        const safeName = (options.projectName ?? project.name)
+            .toLowerCase()
+            .replace(/[^a-z0-9_]/g, '_');
+        const readme = `# ${project.name} - PICO-8 Export
+
+Generated from Nice2Dev project v${project.version}
+
+## Requirements
+
+- PICO-8 ($15 from https://www.lexaloffle.com/pico-8.php)
+
+## Installation
+
+1. Open PICO-8
+2. Type: \`load ${safeName}\`
+3. Press Ctrl+R or type \`run\`
+
+## Files
+
+- \`${safeName}.p8\` - PICO-8 cartridge file
+- \`source.lua\` - Extracted Lua source (for reference)
+
+## PICO-8 Constraints
+
+This export is designed for PICO-8's limitations:
+- **Display**: 128x128 pixels
+- **Colors**: 16 color palette
+- **Code**: 8192 tokens max
+- **Memory**: 32KB cartridge
+- **Sprites**: 128 8x8 sprites
+- **Map**: 128x64 tiles
+- **Sound**: 64 SFX slots
+- **Music**: 64 patterns
+
+## Controls
+
+- ⬅️➡️⬆️⬇️ / ESDF: Move
+- 🅾️ (Z/C): Action 1
+- ❎ (X/V): Action 2
+- P: Pause menu
+
+## Code Structure
+
+\`\`\`lua
+-- _init()    - Called once at start
+-- _update60() - Called 60 times per second
+-- _draw()    - Called after update for rendering
+\`\`\`
+
+### Entity System
+
+\`\`\`lua
+-- Create entity
+local e = make_entity("player", 64, 64)
+
+-- Kill entity
+kill_entity(e)
+
+-- Check tag
+if has_tag(e, "enemy") then
+  -- ...
+end
+\`\`\`
+
+### Scenes
+
+${project.scenes.map((s, i) => `- Scene ${i + 1}: ${s.name} (${s.entities.length} entities)`).join('\n')}
+
+Load scene with: \`load_scene(1)\`
+
+## Customization
+
+### Adding Sprites
+
+1. In PICO-8, press Ctrl+S to open sprite editor
+2. Draw your sprites (8x8 pixels each)
+3. Update entity_types sprite indices
+
+### Adding Sounds
+
+1. Press Ctrl+N for SFX editor
+2. Create sounds in slots 0-63
+3. Play with: \`sfx(0)\`
+
+### Adding Music
+
+1. Press Ctrl+M for music editor
+2. Create patterns using SFX
+3. Play with: \`music(0)\`
+
+## Debug Mode
+
+Set \`game.debug=true\` to show:
+- FPS counter
+- CPU usage
+- Memory usage
+- Entity hitboxes
+
+## Tips
+
+- Keep code under 8192 tokens
+- Use shorter variable names to save tokens
+- Reuse sprites with flip flags
+- Use map for static backgrounds
+- Pool entities to avoid garbage
+
+## Links
+
+- PICO-8 Manual: https://www.lexaloffle.com/dl/docs/pico-8_manual.html
+- PICO-8 Wiki: https://pico-8.fandom.com/
+- Splore: Built-in game browser (type \`splore\`)
+`;
+        this.addTextFile('README.md', readme);
+    }
+}
+/* ── Factory ──────────────────────────────────────────────────── */
+function createPico8Exporter() {
+    return new Pico8Exporter();
+}
+
+exports.Pico8Exporter = Pico8Exporter;
+exports.createPico8Exporter = createPico8Exporter;
+//# sourceMappingURL=Pico8Exporter.js.map