Stage Editor

Guide to using the Stage Editor for creating and arranging stage props and camera zones

The Stage Editor (Stage Builder) is a visual tool for creating and arranging stage layouts in Friday Night Funkin’. It allows you to position sprites, set parallax scrolling, and configure stage elements.

Opening the Stage Editor

1. From Main Menu

   Press ~ (tilde) to open the debug menu, then select Stage Editor

2. From Play State

   While playing a song in debug mode, press the STAGE hotkey to open the old Stage Editor overlay

The Stage Editor is currently in development and features may change. The tool is marked with the FEATURE_STAGE_EDITOR compiler flag.

Interface Overview

The Stage Editor provides a visual canvas for arranging stage elements:

Main Canvas

• Grid Overlay: 10x10 pixel grid for precise positioning
• Stage View: Preview of how the stage looks
• Mouse Controls: Click and drag to position elements
• Camera Controls: Pan and zoom to navigate the stage

HUD Elements

• Info Text: Displays current selection and properties
• Load Image Button: Import new stage sprites
• Save Scene Button: Save current stage layout
• Layer Information: Shows sprite stacking order

Controls

View Controls

Key	Action	Description
H	Toggle HUD	Show/hide the editor UI
Mouse Drag	Pan Camera	Click and drag to move the camera
Ctrl+Mouse Wheel	Zoom	Zoom in/out on the stage
Escape	Toggle Mode	Switch between Movement and Attributes mode

Movement Mode

This is the default mode for positioning sprites:

Key	Action	Description
V	Select Tool	Activate selection cursor
Click	Select Sprite	Select a sprite to edit
Drag	Move Sprite	Reposition the selected sprite
↑↓←→	Nudge	Move sprite by 1 pixel (keyboard)
[	Layer Down	Move sprite back one layer
]	Layer Up	Move sprite forward one layer
Delete	Remove	Delete the selected sprite
Z	Undo	Undo last action

Hold Ctrl while in Movement Mode to temporarily switch to Select Tool

Attributes Mode

Press Escape to switch to this mode for adjusting sprite properties:

Key	Action	Description
←	Decrease Parallax	Reduce scroll factor by 0.1
→	Increase Parallax	Increase scroll factor by 0.1
Escape	Back to Movement	Return to movement mode

The attributes mode text appears at 100% opacity, while movement mode shows at 50% opacity as a visual indicator.

Adding Stage Elements

1. Prepare Image Files

   Save your stage sprite images in PNG format. Recommended to use transparent backgrounds for props.

2. Import Image

   Desktop Only: Drag and drop image files directly onto the editor window

   The file will be:

   • Copied to assets/images/stageBuild/ directory
   • Automatically loaded as a stage sprite
   • Positioned at the mouse cursor location
3. Position Sprite

   Use the mouse or arrow keys to position the sprite exactly where you want it

4. Adjust Layers

   Use [ and ] to move the sprite behind or in front of other elements

Working with Parallax Scrolling

Parallax scrolling creates depth by moving background elements at different speeds:

Understanding Scroll Factor

The scroll factor determines how much a sprite moves with the camera:

• 1.0: Moves normally with camera (foreground)
• 0.5: Moves at half speed (middle ground)
• 0.0: Doesn’t move at all (fixed background)
• >1.0: Moves faster than camera (rarely used)

1. Select Sprite

   Click on the sprite you want to adjust

2. Switch to Attributes Mode

   Press Escape to enter Attributes mode (text will appear at full opacity)

3. Adjust Parallax

   • Press ← to decrease scroll factor (move slower/further back)
   • Press → to increase scroll factor (move faster/closer)
   • Each press changes by 0.1
4. View Properties

   The info text shows: [filename] - parallax: (x, y)

Layer Management

Stages use a layer system for proper sprite ordering:

Layer Basics

• Layer 0: Furthest back
• Higher Numbers: Closer to front
• Automatic Assignment: New sprites get next available layer

Reordering Layers

1. Select Target Sprite

   Click on the sprite you want to reorder

2. Move Layer

   • Press [ to move one layer back (swap with previous sprite)
   • Press ] to move one layer forward (swap with next sprite)
3. Verify Order

   The layer number updates automatically, and sprites re-render in correct order

Layers automatically maintain the sorting order. Moving a sprite updates the layer property for both the moved sprite and the swapped sprite.

Mouse Tools

The Stage Editor changes the cursor to indicate the current tool:

Tool Types

1. SELECT: Default cursor for selecting sprites
2. GRAB: Hand cursor when hovering over a selectable sprite
3. GRABBING: Closed hand cursor while dragging a sprite

Selection System

• Click on a sprite to select it (cursor changes to GRAB)
• Selected sprite shows in the info display
• Click and drag to move (cursor changes to GRABBING)
• Release to place sprite in new position
• Position change is tracked for undo functionality

Camera Controls

Pan Camera

• Middle Mouse + Drag: Pan the view around the stage
• Alternative: Use the MouseUtil.mouseCamDrag() function

Zoom Camera

• Ctrl + Mouse Wheel: Zoom in/out
• Zoom Center: Zoom centers on mouse position
• Grid Scales: Grid overlay scales with zoom level

Saving Your Stage

1. Arrange All Elements

   Position all sprites and set their parallax values

2. Click Save Scene

   Click the “Save Scene” button in the HUD

3. Output Format

   The stage data is saved with:

   • Sprite positions (x, y)
   • Scroll factors (parallax)
   • Layer order
   • Image filenames

Make sure to test your stage in-game after saving to verify positions and parallax effects work as intended.

Undo System

The Stage Editor includes an undo system for common operations:

Undoable Actions

• Moving sprites (position changes)
• Changing sprite selection
• Adjusting layer order

Using Undo

• Press Z to undo the last action
• The action and position queues maintain history
• Undo reverses the operation (e.g., move back, restore old selection)

The undo system uses action and position queues that track functions and their parameters for reversal.

Stage Data Structure

Stages use the following sprite properties:

{
  imgName: String,          // Filename of the sprite
  x: Float,                 // X position
  y: Float,                 // Y position  
  scrollFactor: {           // Parallax scroll amounts
    x: Float,
    y: Float
  },
  layer: Int                // Z-order layer index
}

Advanced Features

Drag and Drop (Desktop Only)

On desktop builds, you can drag image files directly:

1. Prepare Images

   Have your stage prop images ready in PNG or JPEG format

2. Drag onto Window

   Drag the file from your file explorer onto the Stage Editor window

3. Auto-Import

   The editor will:

   • Copy file to stageBuild folder
   • Create a temporary copy for editing
   • Spawn sprite at mouse cursor position
   • Automatically focus on MOVEMENTS mode

Mouse Offset Tracking

When dragging sprites:

• The editor tracks where you grabbed the sprite
• Maintains offset during drag (doesn’t snap center to cursor)
• Smooth dragging experience
• Old position stored for undo functionality

Performance Considerations

The Stage Editor uses FlxTypedGroup for sprite management, which efficiently handles sprite rendering and updates.

• Grid overlay uses FlxGridOverlay for performance
• HUD elements render on separate camera
• Sprites sort automatically by layer
• Mouse events optimized with FlxMouseEvent.reorder()

File Organization

Stage files are organized in the project:

assets/
  images/
    stageBuild/           # Temporary staging area
      stageTempImg.png    # Active editing image
      [filename].png      # Imported images
  data/
    stages/
      [stage-id].json     # Stage configuration

Integration with Other Tools

• Chart Editor: Select which stage to use for a song
• Animation Editor: Position characters on the stage
• Debug Mode: Preview stages in-game with F5 hot reload

Tips and Best Practices

Naming Conventions

Use descriptive filenames:

• bg_sky.png for background sky
• prop_speakers.png for stage props
• fg_overlay.png for foreground overlays

Layer Planning

Plan your layer order before importing:

1. Far background (sky, distant objects)
2. Mid background (buildings, scenery)
3. Stage floor
4. Props and set pieces
5. Character positions (not in editor, but plan for)
6. Foreground effects and overlays

Parallax Guidelines

Standard parallax values:

• Sky: 0.1 - 0.3
• Distant background: 0.5 - 0.7
• Stage floor: 0.9 - 1.0
• Foreground props: 1.0
• Fixed UI elements: 0.0

Testing Workflow

1. Create basic stage layout
2. Save and exit editor
3. Test in Chart Editor or Play State
4. Note any adjustments needed
5. Return to Stage Editor to refine
6. Iterate until perfect

Related Tools

• Chart Editor - Assign stages to songs
• Animation Editor - Position character animations
• Debug Hotkeys - Quick access shortcuts