Skip to content

Custom Stages

Jump to bottom
MaybeMaru edited this page Jun 4, 2024 · 1 revision

1. Stage Basics

the stage is a fundamental part of fnf modding, in this engine like many other softcoded engines it is broken up into two files json and hx
while you would only need a json file to add objects some complex things like sprite logic and shader effects will need to be scripted in via haxe

2. Stage Json

{
    "library": "",
    "skin": "default",

    "zoom": 1.05,
    "camBounds": [-9999, -9999, 9999, 9999],
    "startCamOffsets": [0.0, 0.0],

    "gfOffsets": [0.0, 0.0],
    "dadOffsets": [0.0, 0.0],
    "bfOffsets": [0.0, 0.0],

    "gfCamOffsets": [0.0, 0.0],
    "dadCamOffsets": [0.0, 0.0],
    "bfCamOffsets": [0.0, 0.0],

    "cacheImages": [],
    "layersOrder": ["bg", "gf", "dad", "bf", "fg"],
    "layers": {
        "bg": [],
        "gf": [],
        "dad": [],
        "bf": [],
        "fg": []
    }
}

2.1 Stage Values

  • library: string

    adds an path that sprites and assets can be pulled from
    this effects any asset that is pulled from paths

  • skin: string

    this changes the skin that the ui uses, you can put "pixel" if the song is a pixel song or check out how to make a your own Custom Skin

  • zoom: number

    this changes the defaultCamZoom the game uses to whatever you want it to be, the higher the value the more your zoomed in

  • camBounds: array<min-x, min-y, max-x, max-y>

    this changes the maximum area that the screen can transitioned into
    in most cases you will not need to use this

  • gfOffsets, dadOffsets, bfOffsets: array<offset-x, offset-y>

    the offsets of the character
    these values is negative compared to stage systems like Psych or Codename

  • gfCamOffsets, dadCamOffsets, bfCamOffsets: array<offset-x, offset-y>

    the camera offset that is added on top of the normal character json offset

  • cacheImages: array<string>

    these are for images that will be used by created sprites later along the sprites
    just add the path of your image from image/

    • example

      if your image is in images/stage/effects/ and its name is boom.png
      you would then put stage/effects/boom to cache the image

  • layersOrder: array<string>

    the order of the layers that the game uses to order sprites

  • layers: map<string, array<stageObject>>

    separated plains that you can use to add objects

    • example

       {
 	"layers": {
 		"bg": [
 			{
 				"tag": "stageBack",
 				"imagePath": "stageback",
 				"position": [-600,-200],
 				"scrolls": [0.9,0.9]
 			},
 		]
 	}
 }

2.2 Stage Objects

stage objects are the sprites created from the json file that then are added to the layer that they are created from

2.2.1 Stage Object Template

{
    "tag": "",
    "imagePath": "",
    "scale": 1.0,
    "position": [0.0, 0.0],
    "scrolls": [1.0, 1.0],
    "anims": [],
    "flipX": false,
    "flipY": false,
    "allowLod": true,
    "antialiasing": true,
    "blend": "normal",
    "alpha": 1.0
}

2.2.2 Stage Object Values

  • tag: string

    used by the engine as a key for the sprite to be accessed later on and as the tag when the sprite gets added to the StageScript

  • imagePath: string

    like the cache image this uses the same principles

  • scale: number

    changes the width and height of the sprite
    useful for when your sprite is too big to fit in with the other sprites

  • position: array<x, y>

    this changes the position of the sprite like the character offsets

  • scrolls: array<scroll-x, scroll-y>

    this adds parallax factors to the sprites allowing it to move with the camera movement

  • anims: array<spriteAnimation>

    this adds a animation to the sprites with room for looping offsets of their own

  • flipX: bool

    flips the sprite across the x axis

  • flipY: bool

    like flipX but instead of the y axis

  • allowLod: bool

    if true this prevents the quality massacre of the Lod modes

  • antialiasing: true

    this changes the render type of the sprite
    useful for pixel assets

  • blend: string

    this changes the blendmode of the sprite

  • alpha: number

    this changes the transparency of the sprite

2.2.3 Stage Object Animation

this is a way to add animations onto the StageSprites in a friendly and easy way

2.2.2.1 Animation Json Template

{
    "animName": "idle",
    "animFile": "idle",
    "offsets": [0.0, 0.0],
    "indices": [],
    "framerate": 24,
    "loop": false
}

2.2.2.2 Animation Json Values

  • animName: string

    the key that you will use to play the animation later on

  • animFile: idle

    the key in the xml or json the sprite came from

  • offsets: array<offset-x, offset-y>

    the animation offsets for that sprite in particular
    think the character editor

  • indices: array<number>

    the indices used to manually determine the animation frames

  • framerate: number

    the fps that the animation will play at

  • loop: bool

    if you want the sprite to loop forever
    automatically plays the animation if you pick this value

3. Stage Scripting

Stages have a additional hx script on top of the json file that can be used to more intently access the stage objects along with some functions to access the sprites and layers

3.1 Stage Script

stage scripts implements the objects created into the script

for example if you made an object with the tag "little_guy_5000" you can access it like little_guy_5000.x += 20; inside of the stage script

3.2 Change Stage Event

there is a stage change event that calls two callbacks for the stage change event

  • hideStage() | called when the stage is stage is being changed into a different stage so all the assets need to hide

  • changeStage() | called when the stage is being changed into so unhide the assets here

by default the event should work without these but if for some reason it is not working use these functions to hide them manually

3.3 Stage Layer Related Functions

  • makeLayer(?maxSize:number):layer | makes a new layer that you can add into

  • addLayer(index:number = 0, layer:layer, key:string) | uses the output from the makeLayer function to add a new layer to the list with the key with index of your choosing

  • getLayer(key:string):layer | gets the layer that is added with the key

  • existsLayer(key:string):bool | returns if the layer with the key exists or not

4. Stage Debugger

as of 0.2 the stage debugger can only view the stage and nothing much more

Stage Docs Wrighten by BlueColorsin

Clone this wiki locally