StarFox Level Editor

SFXedit 0.93 Documentation.




 
  
     
       
        SFXedit 
          0.93 beta documentation.

        ©2005 
          VL-Tone -- ant00@lycos.com

          

          http://pages.infinit.net/voxel/

          http://membres.lycos.fr/nes3d/

          

        
    
     
      This is a prerelease of an 
        upcoming Starfox level editor application.

        

        It contains some bugs and may corrupt your ROM file(s), so only use it 
        on backups.

        

        I don’t provide the ROM file, and don’t ask me where to find 
        them.

        I hope you are or were once a proud StarFox cartridge owner.

        

        It can -only- be used with version 1.0 of the Starfox ROM.

        Version 1.0 has a red contour over the title screen logo.

        Version 1.2 has a brown contour.

        Japanese version has a blue contour.

        

        I’ll add support for these other versions some day (including SFX 
        Competition).

        

        New in SFXedit 0.93: the program will check for the correct 
        StarFox US 1.0 version.

        If the version is not US 1.0, the program will tell you what version you 
        were trying to open.

        Just click the open ROM file button again and chose the correct version.

        

        Now for an explanation of the level editor basics. Hexadecimal knowledge 
        is required.

        

        There are 2 banks used for the level in the game at $000005 and $00000D.

        Most if not all hex adress used in the editor are in reverse byte order, 
        and 

        that may change in the future. 

        

        The real ROM addresses of these can be found by multiplying the high byte 
        by 

        32768 and then adding the remaining 16-bit chunk +512

        

        The editor will edit an extra 32k bank at $000020 provided you extended

        the ROM by at least 32k (32768 bytes). The extra empty bank must be filled

        with FFs so to extend a SNES ROM, just add at least a 32768 bytes chunk 
        of FFs.

        The editor will auto-detect if the ROM has been extended.

        

        I’ll add the possibility too access more extra banks soon.

        

        In the editor you can

        -Select multiple objects using the shift key. 

        

        -Copy them and paste them in empty spaces. 

        

        -Delete objects to free space. 

        

        -Please note that empty spaces (FF) will crash the game if it reads them.

        

        -That’s why I suggest you work in the extra bank instead of trying 
        to modify

        the original levels too much.

        

        -The “Open ROM” button is used to open a ROM.

        

        -The “Run in SNES9x” should open the ROM in your Emulator.

        

        -This run function may or may not work :)

        

        -The revert file location is only asked if it’s needed (when you 
        revert an object)

        

        -The revert file location is reseted when you open a save/edit ROM.

        

        -”Revert Selection” only works on objects that have the same 
        type in the revert ROM.

        

        -Click on a location in the blue list to jump to other levels, default 
        is Training. 

        

        -You can edit any property of any object that has it’s value hi-lighted 
        by 

        clicking on it. You can even edit the br1, br2, br3 and b4 properties 
        of h78 

        asm objects without having to edit the code. 

        

        -Very important feature: if you click on an editable property name,

        many properties will display a pop-up menu, where you can chose pre-defined

        values with descriptions, very useful for objnum:, objtyp: , objid: and 
        bhnum:.

        

        -If you click on “warp:” or “br1:” property though. 
        the editor will jump to the warp 

        address. Use the Go Back button to get back to where you where. 

        

        -When “duplicate at:” is selected, the duplicate button will 
        duplicate objects 

        starting at the next empty space found after the address (default is “000020” 
        

        the start of the empty extra bank) 

        

        -If the next empty location is too far or there is not enough space there,

        the editor will spit out an error.

        

        -Most levels are initialized in the 0D bank but jump back in the 05 bank, 
        you 

        can use this warp object to jump to a new level at the 20 bank for example. 
        

        

        -To create new objects, you can choose them by clicking the popup menu 
        field at 

        the right of the “new object” button, then click the button. 
        

        

        -To paste and create objects, you must select an empty byte object that 
        is 

        followed by enough empty bytes objects to fit the object length. 

        

        -When you click on the animated icon for an object it will open it in 
        the 3d 

        viewer on top. 

        

        -You can rotate objects in the 3d viewer by dragging in the 3d view, holding 
        

        alt will rotate on another axis. 

        

        -You can use the “.” and “,” keys to step frames 
        of an object when the 

        animation is stopped. 

        

        -When you click on the asm property of an h78 chunk, you get a disassembled 
        

        version of the included asm code in the red upper right text field. 

        

        -You can set initial conditions for the register emulation bits, most 
        h78 chunk

        don’t require a change from the default. (this only affects disassembling)

        

        -If you click the Hex Data Mode button, you’ll get an hexdata: property 
        field 

        for objects instead of the individual properties. 

        

        -The hexdata: property fields contains raw hex bytes not including the 
        first 

        byte which is the “objtyp:” byte. 

        

        -You can copy and paste values when they are selected. You can even copy 
        some 

        uneditable properties like “addr:” to a “warp:” 
        property. 

        

        -Click on “Normal Mode” to get the normal view of properties.

        

        The ztimer value is a decrementing counter that is very important to the 
        game 

        engine. Until this counter reach zero, the games moves forward without 
        drawing 

        and loading anything new.

        

        When the value reaches zero, the next object is loaded and displayed if 
        it’s a 

        polygon object. The game will then load and draw any following objects 
        at a 

        position relative to the current one, until it reaches a new ztimer setting. 
        

        

        The h8A and h12 objects are used to set the ztimer, but most objects with

        x y z coords also can set the ztimer.

        

        It’s used to make gaps in game, it makes the x y z coord system 
        always 

        relative to the last ztimer setting.

        
    
     
      The object viewer 
          is new in version 0.93.

          

          Click the "object viewer" button to open it.

          

          -You get access to the same 3d and animation controls as in the level 
          editor's mini viewer.

          

          -The list of objects in the blue text fields at the right is referring 
          to all documented objects.

          

          -Clicking on the blue text field will open and view the object.

          

          -Descriptions are preliminary, and some objects are not displayed and 
          texture support is minimal.

          

          -The "export to .obj file" button will save a monochrome Wavefront 
          .OBJ format file 

          from the current object in view. The .OBJ file is saved in the application's 
          enclosing folder.

          Animated objects will create multiple .OBJ files when exporting.

          

          -The color palette buttons will switch the palette for the current object, 
          changes are not saved.

          

          -At the bottom of the object viewer interface is the 28 bytes header 
          that exists for every 3d 

          object in Starfox.It includes information about where to find the polygon 
          mesh data, scaling,

          palette set and other info which I didn't manage to figure out yet (I 
          suspect those are about 

          collision regions).

          

          -You cannot save changes to this header data for now using the editor, 
          but obviously, 

          I'm planning to add support for header editing.

          

          -Note the object viewer is not an object editor (not yet!) so nothing 
          you change in it will

          have any impact on the level editor and your ROM file.

          

          -To get back to the level editor from in the object viewer, click the 
          "Level Editor" button.(duh!)

          

          To be added in a future release is text editing so the you can edit 
          text found 

          in the game like dialogs, bosses and level descriptions.

          

          I'm aiming to implement a WYSIWYG 3d editor that will be much more interactive 
          than

          the current text/menu based editor. 

          

          Still this part of the interface will still be needed to allow a more 
          complete control of 

          what can happen in the game like loops, warps, music and other events.

          

          I'm also planning to add an "easy mode" where people won't 
          have to deal with hexadecimal.

          

          Still many of the original levels are complicated by themselves and 
          even an easy to use 

          editor won't help with those.

          

          Until then, you can experiment on your own with the editor, which is 
          overall useable once

          you figure out the basics of it :)

        
    
  
  

  Here 
    are descriptions for all chunk types used in the game.

  

 


  
     
      h86 len: 14 Object+behavior 
        with 16 bits coords
    
     
      This is one of the common 
          way to display 3d polygonal objects in the game.16-bits x y and z coordinates 
          are used (-32768 to +32768)

          

          objad: uses 2 bytes to refer to a polygonal object.

          

          bhaddr: uses 3 bytes to refer directly to a behavior. 
          

          A pop-up menuis also available for this property with all the values 
          used in the game

    
  

 


  
     
      h00 len: 11 Object+behavior 
        with 16 bits coords
    
     
      This one also uses 16 bits 
          coordinates.

          

          Instead of the objad: property, objnum: 
          is used to refer to the 

          polygon object. This restricts you to 256 predefined values.

          

          The objad: property is not editable in this chunk type.

          It's being displayed for reference.

          

          Much the same, bhnum: replaces bhaddr: in 
          h00 chunks,

          and only bhnum: is editable and is restricted to 256 
          predefined values.

    
  

 


  
     
      h74 len: 10 Object/behavior 
        with 16 bits coords
    
     
      This chunk type also uses 
          16 bits coords .

          

          It uses only one byte (bhnum:) to refer to a polygon 
          object and a behavior at the same time.

          

          Each bhnum: value has an associated 1 byte value referring 
          to a polygon object. 

        You can see this value in 
          the non editable objnum: text field.

    
  

 


  
     
      h70 len: 7 Object+behavior 
        with 8 bits coords
    
     
      This chunk type is like 
          h00 but with 8 bits coordinates. 

          

          The z coordinate is ranging from 0 to 255 (so they are only positive) 
          when 8 bits coords are used.

          

          objnum: is used to refer to the polygonal object (one 
          byte).

          bhnum: is used to refer to a predefined behavior (one 
          byte).

          

          bhaddr: and objid: are non editable 
          in h70, their values can be 

          copied and pasted in other editable bhaddr: and bhnum: 
          fields.

    
  

 


  
     
      h76 len: 6 Object/behavior 
        with 8 bits coords
    
     
      This chunk type is like 
          h86 but with 8 bits coordinates. 

          

    
  
  

    

     
      h0A len: 16 Random 
        group behavior with 16 bits coords
    
     
      This chunk type has 16 
          bits x, y and z coordinates.

          It also contains a 5 bytes random_group: property.

          The main use of this object is to generate multiple objects

          at random or semi random position.

        It's used to generate asteroid 
          fields and other randomized swarms.

          

          Click on the random group property to get a pop-up menu

          with all the known types with descriptions.

          

          The objad: property is a 2 bytes value referring to 
          polygon objects.

          It's not always used by the h0A depending on the swarm type.

    
  
  All the previously described 
    polygon objects chunk types include 

    a ztimer: property, which is defined earlier in the document.

   



  
     
      h78: len:varies. Pure 
        ASM code block.
    
     
      This chunk type will execute 
          imbeded SNES code and then go back to the game.

          

          When you click on the asm: property, the code will get disassembled 
          in the red asm text field. 

          

          You can only observe the listing, not edit it. Note that RTL in a h78 
          block means "go back to the game" and the command before,

          usually LDX is used to determine the jump back address.

          

          If you really think you can edit the raw code, you can use the Hex Data 
          mode.

          

          The editor will try to automatically find those "branches"

          and make them editable in the br1: br2: br3: and br4: 
          field.

          

          The brx: properties will refer to 
          2 bytes addresses in the 

          current bank ie: XXXX05, XXXX0D or XXXX20.

          

    
  

 


  
     
      h2C len: 6 Warp to 
        2 bytes address in current bank.
    
     
      This chunk type is used 
          to warp to a 2 bytes address in the current bank, but only when a predefined 
          condition is met. 

        The condition: 
          property is 3 bytes long and refers to a specific address where the 
          condition is checked. 

        You can use the included 
          pop-up menu to access all the values that are used in the game.

        For example it's used in 
          the Spaceship Armada level to decide if the arwing will enter inside 
          a ship or pass beside it.

          

          It's also used to loop bosses level parts until they are destroyed.

          

    
  

 


  
     
      h5E len: 6 Screen 
        transition
    
     
      Transitions and other unknown 
          events. 

        Use the pop-up menu to get 
          a list of values used in the game.

          

    
  

 


  
     
      h04 len: 5 Loop segment 
        x times
    
     
      Used in the game loop to 
          any address in the current bank using 2 bytes ie: XXXX05, XXXX0D or 
          XXXX20. The loop will occur X number of times then the game will continue 
          with the next object.

        Note that when moving/duplicating 
          parts of levels you have to manually change the destination address 
          for h04 loops, and other warps like h2E and h28, and h78 brx: warp properties.

          

    
  

 


  
     
      h36 len: 4 Rotates 
        previous polygon object
    
     
      Will rotate the last displayed 
          polygon object according to a one byte rotation mode and 2 bytes angle 
          or rotation speed value.

          

          Modes include static rotation to specific angles on each of the 3 axis's. 
          There are also animated modes were an object rotates by itself on a 
          given axis at a given speed.

          

          The pop-up menu for this one needs to be completed.

          

        
    
  

 


  
     
      h2E len: 4 Warp to 
        3 bytes address
    
     
      h28 len: 4 Warp to 
        3 bytes address, add to stack
    
     
      These chunk objects will 
          warp to anywhere in the ROM

          it uses the same 3 bytes format as the addr: field.

          

          You can even copy and paste those addresses between chunks.

          The difference between the two types is that h28 is a special warp 

          object that remembers where it got launched from. When a h2A object 
          is reached, the game jumps back to this stored address.

          

          Jump back addresses are added to a "stack" so that you can 
          use 

          multiple h28 warps and get back to the point where you left by using 
          the same amount of h2A objects. If you use a h2A while being in the 
          lowest level of the stack, the game will exit the level and return to 
          the level selection screen.

          

          There is a fixed limit to the "recursion" that you can have.

          For example, if you use a h28 warp to loop a level endlessly with no

          h2A objects inside the loop, the game will freeze after a few dozens 
          

          of loops. So don't do that :)

          

          h2E warps can be used over and over and anywhere in the game.

          They don't use h2A objects so if you want to jump back you have to 

          do it manually using another h2E object.

          

          The h28 and h2E objects are the key to create new levels, use themto 
          jump to empty spaces. 

          

          Most levels start with initialization chunks in bank "0D" 
          then warp

          to the main level data in bank "05" using a h28 object.

          

          You can have this address point to any part of the game, including new 
          levels you created in the empty spaces. 

        Just use a h2A object at 
          the end of your level data so that the game ends the level normally.

          

    
  

 


  
     
      h10 len: 3 Setup Level 
        BG, Music etc.
    
     
      Basic initialization of 
          the level, changes the background graphics,

          the music and other aspects such as the flight mode.

          

    
  
   

  
     
      h8C len: 3 Behavior 
        for previous object (16-bits)
    
     
      This chunk type attaches 
          to the last showed polygonal objects and

          is used to give it a complicated behaviors that are the basis of the 
          game.

          

          Those behaviors are not the same as one used inside the polygon object 
          chunks.

          

          These behaviors includes: Flying on many complicated paths, sometimes 
          shooting different types of lasers aimed at Fox. 

          

          Characters dialog can be triggered. Many "plots" are setup 
          using h8C chunks. For example one behavior puts an enemy coming from 
          far away, attacking you. If you don't shoot it, a teammate will fly 
          by and shoot it for you, blabbering something about it.

         There are different sets 
          of these and many are character specific 

          ie: Slippy is taking more time to rescue you, Falco is the fastest and 
          will brag about it if you don't beat him at it. 

          

          There are also "pairs" of behaviors,one to be applied to an 
          Arwing polygonal object and the other to an enemy object. They are used 
          to create scenarios where one is chasing the other.

          

          All the dialog like "Thank you Fox for saving me bla bla bla" 
          , "ouch!" or "I was gonna get that one!" happens 
          automatically.

          

          There are many sets of these pairs using different paths. Other h86 
          behaviors includes the flying credits from the end.

          

          Note that mostly h86 behaviors will use the polygon object on which

          it is attached, but sometimes will override it with its own polygon 
          object.

          

          This chunk type also features a pop-up menu with descriptions and values 
          for all the h86 behaviors used in the game.

    
  

 


  
     
      h8A len: 2 Set ztimer 
        with 8 bit value
    
     
      h12 len: 3 Set ztimer 
        with 16 bit value
    
     
      Sets the ztimer to a 8 
          bit or 16 bit value.

          

          The game will move forward without displaying nor loading new chunks 
          until the ztimer reaches zero.

          

          Used to make level gaps and time delays in the game.

          

    
  

 


  
     
      h64 len: 2 Init camera?
    
     
      It's found only at the 
          start of level and seems to reset the camera.

          Is always followed by h66.

          

    
  

 


  
     
      h76 len: 6 Object/behavior 
        with 8 bits coords
    
     
      This chunk type is like 
          h86 but with 8 bits coordinates. 

          

    
  

 


  
     
      h14 len: 2 Changes 
        Music
    
     
      To change the music anywhere 
          in a level. Value "F0" fades out.

          No pop up menu yet.

          

        
    
  
   

  
     
      h2A len: 1 Jump back 
        from warp
    
     
      As described in the h28 
          explanation, will make the game jump back to just after the last h28 
          was called.

          

          If used at the "bottom" of the stack, when no h28 have been 
          used, the game will exit the level and get back to the level selection 
          screen.

          

    
  

 


  
     
      h5A len: 1 Palette 
        set change?
    
     
      I'm not too sure about 
          this one but it seems to override the palette set for the previous object.

    
  
   

  
     
      h02 len: 1 Fades music 
        out then loops empty level
    
     
      Used at the end of some 
          levels?

          

    
  
   

  
     
      h0E len: 1 Shows current 
        stage number
    
     
      Displays "STAGE: X"

          

    
  
   

  
     
      h44 len: 1 Fades to 
        black
    
     
      Fades the screen to black.

          

    
  

 


  
     
      h84 len: 1 Palette 
        set change?
    
     
      Not sure about this one 
          yet.

          

    
  
   

  
     
      h4E len: 1 Unknown 
        use.
    
     
      This chunk type is one 
          byte and I don't know its use yet.