Terraria world file - typescript

Terraria world file parser written in typescript

\- supports maps from 1.3.5.3 to 1.4.4.9

Feel free to contribute 🌳

Installation

https://www.npmjs.com/package/terraria-world-file

``bash
npm install terraria-world-file
`
`bash
pnpm add terraria-world-file
`
`bash
yarn add terraria-world-file
`
`bash
bun add terraria-world-file
`

Usage

`typescript
import { fileLoader } from 'terraria-world-file/node'
import { FileReader, FileSaver, Position, TownNPC } from 'terraria-world-file'
import * as fs from 'node:fs'

const parser = await new FileReader().loadFile(fileLoader, '/map.wld')
const world = parser.parse()

const spawnPosition: Position = {
x: world.header.spawnTileX,
y: world.header.spawnTileY
}

const wizard: TownNPC = {
id: 108,
name: 'Gandalf',
position: spawnPosition,
homePosition: spawnPosition,
homeless: true,
}

world.NPCs.townNPCs.push(wizard)

console.log(Wizard has appeared at your base!)

const newFile = new FileSaver().save(world)
fs.appendFileSync('/map.wld', Buffer.from(newFile))
``

Documentation:

Up to date Typedocs

$3

constructor  new terrariaWorldParser()



node method  loadBuffer(buffer buffer)

node method  loadFileSync(string path)

node method  async loadFile(string path)

browser method  async loadFile(File file)

— Loads file buffer

— Returns instance



method  parse([object options])

        string array  options.sections

        — Sections to parse

        — Default: ["fileFormatHeader", "header", "tiles", "chests", "signs", "NPCs", "tileEntities",

                           "weightedPressurePlates", "rooms", "bestiary", "creativePowers", "footer"]

        boolean  options.ignorePointers

        — Disables checking whether buffer offset matches the next section pointer

        — Use if some sections are corrupted

        — Default: false

        boolean  options.ignoreBounds

        — Fills the data with zeros if the buffer is outside bounds

        — Use if some sections are missing

        — Default: false

        function  options.progressCallback(int percent)

        — Called when loading progress changes

— Parses file

— Returns buffer
##

constructor  new terrariaWorldSaver()



browser method  save(object options)

        object  options.world

        — Same object structure as parser return object

        — Required

        function  [options.progressCallback(int percent)]

        — Called when loading progress changes

— Saves object

— Returns buffer



TODO: node method  save(object options)

— If you are reading this and want to help, you can create a pull request :)
##

Error  TerrariaWorldParserError

| or

Error  TerrariaWorldSaverError

        string  name = "TerrariaWorldParserError"

        | or

        string  name = "TerrariaWorldSaverError"

        string  message = onlyFriendlyMessage + ":\n" + onlyName + ": " + onlyMessage

        string  onlyFriendlyMessage

        — user friendly error message

        string  onlyName

        — original thrown error name

        string  onlyMessage

        — original thrown error message

Return object:

object  fileFormatHeader

Type | Variable | Description
-----------------|-------------|-----------------------------------------------------------------------------------
int32 | version | map file version
7 bytes string | magicNumber | file format magic number
uint8 | fileType | terraria's file type
uint32 | revision | map was saved count
uint64 | favorite | favorite
int32 array | pointers | offsets of sections
bool array | importants | tile frame importants (animated, big sprite, more variants...)
index = block id

object  header

Type | Variable | Description
---------------|---------------------------------|------------------------------------------------------------
string | mapName | map name
string | seedText | map seed
uint64 | worldGeneratorVersion | version of the world generator, returns 8 bytes array
uint8 array | guid | guid of the map
string | guidString | guid of the map (only browser parser)
int32 | worldId | map ID
int32 | leftWorld | map dimesion in pixels
int32 | rightWorld | ^
int32 | topWorld | ^
int32 | bottomWorld | ^
int32 | maxTilesY | map dimension y in tiles
int32 | maxTilesX | map dimension x in tiles
int32 | gameMode | map game mode
only >1.4.0.1
bool | drunkWorld | drunk world (seed) enabled
only >1.4.0.1
bool | getGoodWorld | good world (seed) enabled
only >1.4.0.3
bool | getTenthAnniversaryWorld | Tenth Anniversary world (seed) enabled
only >1.4.2.3
bool | dontStarveWorld | Dont Starve world (seed) enabled
only >1.4.3
bool | notTheBeesWorld | Not the bees world (seed) enabled
only >1.4.3
bool | remixWorld | Remix world (seed) enabled
only >1.4.4
bool | noTrapsWorld | No traps world (seed) enabled
only >1.4.4
bool | zenithWorld | Zenith world (seed) enabled
only >1.4.4
bool | expertMode | expert mode
only 1.3.5.3
int64 | creationTime | time of creation, returns 8 bytes array (Datetime.ToBinary)
uint8 | moonType | moon type
int32 array | treeX | x positions where corresponding treeStyle ends
int32 array | treeStyle | tree styles
int32 array | caveBackX | x positions where corresponding caveBackStyles ends
int32 array | caveBackStyle | cave background styles
int32 | iceBackStyle | ice underground/cavern background style
int32 | jungleBackStyle | jungle underground/cavern background style
int32 | hellBackStyle | underworld background style
int32 | spawnTileX | position x of the spawn point
int32 | spawnTileY | position y of the spawn point
double | worldSurface | y dimension where cavern starts
double | rockLayer | y dimension where underground starts
double | tempTime | current time
bool | tempDayTime | is day time
int32 | tempMoonPhase | moon phase
bool | tempBloodMoon | is blood moon happening
bool | tempEclipse | is eclipse happening
int32 | dungeonX | position x of the dungeon base
int32 | dungeonY | position y of the dungeon base
bool | crimson | has crimson
bool | downedBoss1 | eye of cthulu killed
bool | downedBoss2 | eater of worlds killed
bool | downedBoss3 | skeletron killed
bool | downedQueenBee | queen bee killed
bool | downedMechBoss1 | the destroyes killed
bool | downedMechBoss2 | the skeletron prime killed
bool | downedMechBoss3 | the twins killed
bool | downedMechBossAny | any mechanical boss killed
bool | downedPlantBoss | plantera killed
bool | downedGolemBoss | golem killed
bool | downedSlimeKing | slime king killed
bool | savedGoblin | goblin saved
bool | savedWizard | wizard saved
bool | savedMech | mechanic saved
bool | downedGoblins | goblins endured
bool | downedClown | clown killed
bool | downedFrost | frost legion endured
bool | downedPirates | pirates endured
bool | shadowOrbSmashed | shadow orb / crimson heart smashed
bool | spawnMeteor | can meteor spawn
uint8 | shadowOrbCount | shadow orbs / crimson hearts smashed count (x/3)
int32 | altarCount | altars smashed count
bool | hardMode | hardmode
bool | afterPartyOfDoom | ?
only >1.4.4
int32 | invasionDelay | ?
int32 | invasionSize | ?
int32 | invasionType | type of an event
double | invasionX | ?
double | slimeRainTime | ?
uint8 | sundialCooldown | cooldown of the Enchanted Sundial
bool | tempRaining | is currently raining
int32 | tempRainTime | current rain time
float | tempMaxRain | ?
int32 | oreTier1 | tier 1 hardmode ore block id
int32 | oreTier2 | tier 2 hardmode ore block id
int32 | oreTier3 | tier 3 hardmode ore block id
uint8 | setBG0 | forest background style
uint8 | setBG1 | corruption background style
uint8 | setBG2 | jungle background style
uint8 | setBG3 | snow background style
uint8 | setBG4 | hallow background style
uint8 | setBG5 | crimson background style
uint8 | setBG6 | desert background style
uint8 | setBG7 | ocean background style
int32 | cloudBGActive | ?
int16 | numClouds | clouds count (max 200)
float | windSpeed | wind speed
string array | anglerWhoFinishedToday | name of players that completed angler quest
bool | savedAngler | angler saved
int32 | anglerQuest | id of the current angler quest (probably)
bool | savedStylist | stylist saved
bool | savedTaxCollector | tax collector saved
int32 | invasionSizeStart | ?
int32 | tempCultistDelay | ?
int32 array | killCount | kill counter of the enemies (index == id)
bool | fastForwardTime | ?
bool | downedFishron | fishron killed
bool | downedMartians | martians killed
bool | downedAncientCultist | cultists killed
bool | downedMoonlord | moon lord killed
bool | downedHalloweenKing | pumpking killed
bool | downedHalloweenTree | everscream killed
bool | downedChristmasIceQueen | ice queen killed
bool | downedChristmasSantank | santa-nk1 killed
bool | downedChristmasTree | mourning wood killed
bool | downedTowerSolar | solar pillar killed
bool | downedTowerVortex | vortex pillar killed
bool | downedTowerNebula | nebula pillar killed
bool | downedTowerStardust | stardust pillar killed
bool | TowerActiveSolar | solar pillar spawned
bool | TowerActiveVortex | vortex pillar spawned
bool | TowerActiveNebula | nebula pillar spawned
bool | TowerActiveStardust | stardust pillar spawned
bool | LunarApocalypseIsUp | lunar event active
bool | tempPartyManual | party started by player
bool | tempPartyGenuine | party started by random
int32 | tempPartyCooldown | party event cooldown
int32 array | tempPartyCelebratingNpcs | NPCs currently celebrating
bool | Temp_Sandstorm_Happening | is sandstorm happening
int32 | Temp_Sandstorm_TimeLeft | time left to sandstorm end
float | Temp_Sandstorm_Severity | severity of the sandstorm
float | Temp_Sandstorm_IntendedSeverity | intented severity of the sandstorm
bool | savedBartender | tavernkeed saved
bool | DD2Event_DownedInvasionT1 | old one's army tier 1 killed
bool | DD2Event_DownedInvasionT2 | old one's army tier 2 killed
bool | DD2Event_DownedInvasionT3 | old one's army tier 3 killed
uint8 | setBG8 | mushroom biome background style
only 1.4
uint8 | setBG9 | underworld background style
only 1.4
uint8 | setBG10 | Forest 2 background style
only 1.4
uint8 | setBG11 | Forest 3 background style
only 1.4
uint8 | setBG12 | Forest 4 background style
only 1.4
bool | combatBookWasUsed | ?
only 1.4
int32 array | treeTopsVariations | ?
only 1.4
bool | forceHalloweenForToday | ?
only 1.4
bool | forceXMasForToday | ?
only 1.4
int32 | savedOreTierCopper | tier 1 normalmode block id
only 1.4
int32 | savedOreTierIron | tier 2 normalmode block id
only 1.4
int32 | savedOreTierSilver | tier 3 normalmode block id
only 1.4
int32 | savedOreTierGold | tier 4 normalmode block id
only 1.4
bool | boughtCat | bought cat
only 1.4
bool | boughtDog | bought dog
only 1.4
bool | boughtBunny | bought bunny
only 1.4
bool | downedEmpressOfLight | killed empress of light
only 1.4
bool | downedQueenSlime | killed queen slime
only 1.4
bool | downedDeerclops | killed deerclops
only 1.4.3
bool | unlockedSlimeBlueSpawn | ?
only >1.4.4
bool | unlockedMerchantSpawn | ?
only >1.4.4
bool | unlockedDemolitionistSpawn | ?
only >1.4.4
bool | unlockedPartyGirlSpawn | ?
only >1.4.4
bool | unlockedDyeTraderSpawn | ?
only >1.4.4
bool | unlockedTruffleSpawn | ?
only >1.4.4
bool | unlockedArmsDealerSpawn | ?
only >1.4.4
bool | unlockedNurseSpawn | ?
only >1.4.4
bool | unlockedPrincessSpawn | ?
only >1.4.4
bool | combatBookVolumeTwoWasUsed | ?
only >1.4.4
bool | peddlersSatchelWasUsed | ?
only >1.4.4
bool | unlockedSlimeGreenSpawn | ?
only >1.4.4
bool | unlockedSlimeOldSpawn | ?
only >1.4.4
bool | unlockedSlimePurpleSpawn | ?
only >1.4.4
bool | unlockedSlimeRainbowSpawn | ?
only >1.4.4
bool | unlockedSlimeRedSpawn | ?
only >1.4.4
bool | unlockedSlimeYellowSpawn | ?
only >1.4.4
bool | unlockedSlimeCopperSpawn | ?
only >1.4.4
bool | fastForwardTimeToDusk | ?
only >1.4.4
byte | moondialCooldown | ?
only >1.4.4

2D objects array  tiles

Type | Variable | Description
-----------------|-----------------|------------------------------------------
uint8 / uint16 | blockId | tile id
uint8 / uint16 | wallId | wall id
int16 | frameX | frame x (tile frame important)
int16 | frameY | frame y (^)
string | slope | edited block (half, TR, TL, BR, BL)
uint8 | blockColor | block paint
uint8 | wallColor | wall paint
string | liquidType | liquid type (water, lava, honey, shimmer)
uint8 | liquidAmount | liquid amount
bool | actuator | contains actuator
bool | actuated | is actuated
bool | wireRed | contains red wire
bool | wireBlue | contains blue wire
bool | wireGreen | contains green wire
bool | wireYellow | contains yellow wire
bool | invisibleBlock | is invisible block
bool | invisibleWall | is invisible wall
bool | fullBrightBlock | is full bright block
bool | fullBrightWall | is full bright wall

objects array  chests

Type | Variable | Description
----------------------------------|----------|-----------------------------------------
string | name | name of the chest
object | position |
\|    int32 | x | position x of the chest
\|    int32 | y | position y of the chest
object array | items |
\|    int16 | stack | stack of the item
\|    int32 | id | id of the item
\|    uint8 | prefix | id of the prefix for the item (modifier)

objects array  signs

Type | Variable | Description
----------------------------------|----------|-----------------------
string | text | text of the sign
object | position |
\|    int32 | x | position x of the sign
\|    int32 | y | position y of the sign

objects array  NPCs

Type | Variable | Description
----------------------------------|--------------|-----------------------------
int32 | id | id
bool | townNPC | is townNPC
bool | pillar | is pillar
bool | shimmered | is shimmered
string | name | name
only townNPCs
bool | homeless | is homeless
only townNPCs
object | position |
\|    float | x | position x of an npc
\|    float | y | position y of an npc
object | homePosition | only townNPCs
\|    int32 | x | position x of npc's home
\|    int32 | y | position y of npc's home

objects array  tileEntities

Type | Variable | Description
------------------------------------------------------------|--------------------|------------------------------------------------------------------------
uint8 | type | tile entity type
int32 | id | tile entity ID
object | position |
\|    int16 | x | position x of the tile entity
\|    int16 | y | position y of the tile entity
object | targetDummy |
\|    int16 | npc | ?
object | itemFrame |
\|    int16 | itemId | ID of the framed item
\|    uint8 | prefix | prefix of the framed item (modifier)
\|    int16 | stack | stack of the framed item
object | logicSensor |
\|    uint8 | logicCheck | type of the logic check (probably)
\|    bool | on | is on
object | displayDoll | only 1.4
\|    objects array | items | size = 8
\|    \|    int16 | itemId | item ID
\|    \|    uint8 | prefix | item modifier
\|    \|    int16 | stack | items stack
\|    objects array | dyes | size = 8
\|    \|    int16 | itemId | dye ID
\|    \|    uint8 | prefix | dye modifier
\|    \|    int16 | stack | dye stack
object | weaponRack | only 1.4
\|    int16 | itemId | item ID
\|    uint8 | prefix | item modifier
\|    int16 | stack | item stack
object | hatRack | only 1.4
\|    objects array | items | size = 2
\|    \|    int16 | itemId | item ID
\|    \|    uint8 | prefix | item modifier
\|    \|    int16 | stack | items stack
\|    objects array | dyes | size = 2
\|    \|    int16 | itemId | dye ID
\|    \|    uint8 | prefix | dye modifier
\|    \|    int16 | stack | dye stack
object | foodPlatter | only 1.4
\|    int16 | itemId | item ID
\|    uint8 | prefix | item modifier
\|    int16 | stack | item stack
bool | teleportationPylon | is pylon
type is determined by its position in the world
only 1.4

objects array  weightedPressurePlates

Type | Variable | Description
----------------------------------|----------|--------------------------------
object : | position |
\|    int32 | x | position x of the pressurePlate
\|    int32 | y | position y of the pressurePlate

objects array  rooms

Type | Variable | Description
----------------------------------|----------|-----------------------
int32 | NPCId |
object : | position |
\|    int32 | x | position x of the room
\|    int32 | y | position y of the room

object  bestiary
— only 1.4

Type | Variable | Description
-----------------------------------|-----------|---------------------------------------
object : | NPCKills |
\|    string | [key] | name of the NPC
\|    int32 | [value] | given NPC kill count
strings array | NPCSights | names of NPCs that player encountered
strings array | NPCChats | names of NPCs that player chatted with

object  creativePowers
— only 1.4

Type | Variable | Description
----------|--------------------------------|--------------------------------
bool | freezeTime | Freeze Time enabled
float32 | modifyTimeRate | Time Speed Slider value
bool | freezeRainPower | Rain Change freeze enabled
bool | freezeWindDirectionAndStrength | Wind Change freeze enabled
float32 | difficultySliderPower | Enemy Difficulty Slider value
bool | stopBiomeSpreadPower | Infection Spread freeze enabled

object  footer

Type | Variable | Description
---------|----------|--------------
bool | signoff1 | always true
string | signoff2 | map name
int32 | signoff3 | map id