Mapdev:mapinfo.lua

From Spring
Jump to navigationJump to search

mapinfo.lua Reference

Download the map blueprint

Thing are set out in sections with all relevant information for that section contained within.

variables are organised as such:

VariableName type [valid range] Required
Default: value, Description

If you notice something is incorrect, fix it please!

General Formatting

check Lua Documentation.

Data Types

int : An integer number. eg. 5
float : A number with decimals. eg 1.023
bool : A value which can be true or false. eg true
string : Text, or more precisely a string of alphanumeric characters. eg "string of characters"
rgb : Three float components, representing red, green and blue components, ranged from zero to one. eg {0.0, 0.0, 0.0}
rgba : Four float components, representing red, green, blue and aplha components, ranged from zero to one. eg {0.0, 0.0, 0.0, 0.0}

Sections

mapinfo

local mapinfo = {
   name        = "MyMap",
   shortname   = "",
   description = "",
   author      = "",
   version     = "",
   --mutator   = "deployment";
   --mapfile   = "", --// location of smf/sm3 file (optional)
   modtype     = 3, --// 1=primary, 0=hidden, 3=map
   depend      = {"Map Helper v1"},
   replace     = {},

   --startpic   = "", --// deprecated
   --StartMusic = "", --// deprecated

   maphardness     = 100,
   notDeformable   = false,
   gravity         = 130,
   tidalStrength   = 0,
   maxMetal        = 0.02,
   extractorRadius = 500.0,
   voidWater       = false,
   autoShowMetal   = true,

   smf = {
      ...
   },

   sound = {
      ...
   },

   resources = {
      ...
   },

   splats = {
      ...
   },

   atmosphere = {
      ...
   },

   grass = {
      ...
   },

   lighting = {
      ...
   },

   water = {
      ...
   },

   teams = {
      ...
   },

   terrainTypes = {
      ...
   },

   custom = {
      ...
   },
}
name type [string] Required
Name of the map
shortname type [string]
description type [string]
The description of the map that shows in the multiplayer battleroom.
author type [string]
Author of the map
version type [string]
version, appended to name.
mutator type [string]
?
mapfile type [string]
location of smf/sm3 file (optional)
modtype type [1-3] Required
1=primary, 0=hidden, 3=map
depend type [?] Required
replace type [?]
maphardness type [?]
Default: 100, Defines how much a map will deform from impacts. Higher values mean less deformation, negative values will result in negative deformation (really funny looking)
notDeformable type [0|1]
Default: 0,Setting it to 1 means that no explosions can deform the map.
gravity type [?]
Default: 130, The force of gravity in units/sec^2
tidalStrength type [?]
Default: 0,The amount of energy which will be given by tidal generators.
maxMetal type [?]
Default: 0.02, How much metal a map square with the maximum metal value gives.
extractorRadius type [?]
Default: 500, The radius of effect that a single extractor will extract from. If two radii intersect, both extractors will suffer from reduced output.
voidWater type [0|1]
Default: 0, Voidwater means there will be no water plane, and all parts of the map under water will be completely transparent, to show the skybox through the map. For example, check Apophis_v2
autoShowMetal type [0|1]
Default: 1, Defines wether the metal map (F4 mode) is shown automatically when a mex is queued for placement.

smf

local mapinfo = {
   ...
   smf = {
      minheight = 1000,
      maxheight = -300,
      smtFileName0 = "",
      smtFileName1 = "",
      smtFileName.. = "",
      smtFileNameN = "",
   },
   ...
}
minheight type [?]
Overrides the minimum map height specified while compiling. Compile time height used if undefined
maxheight type [?]
Overrides the maximum map height specified while compiling. Compile time height used if undefined
smtFileName[N] type [?]
Default: ?, ?

sound

local mapinfo = {
   ...
   sound = {
      preset = "default",

      passfilter = {
         ...
      },

      reverb = {
         ...
      },
   },
   ...
}
preset type [string]
Default: "default", Sets the _reverb_ preset (= echo parameters), passfilter (the direct sound) is unchanged. To get a list of all possible presets check: EFXPresets.cpp

Hint: You can change the preset at runtime via:

  • /tset UseEFX [1|0]
  • /tset snd_eaxpreset preset_name (may change to a real cmd in the future)
  • /tset snd_filter %gainlf %gainhf (may " " " " " " " " )

passfilter

Note, you likely want to set these tags due to the fact that they are _not_ set by `preset`! So if you want to create a muffled sound you need to use them. 

local mapinfo = {
   ...
   sound = {
      ...
      passfilter = {
         gainlf = 1.0,
         gainhf = 1.0,
      },
      ...
   },
   ...
}
gainlf type [?]
Default: ?, ?
gainhf type [?]
Default: ?, ?

reverb

Normally you just want use the `preset` tag but you can use handtweak a preset if wanted with the following tags. To know their function & ranges check the official OpenAL1.1 SDK document. 

local mapinfo = {
   ...
   sound = {
      ...
      reverb = {         
         --density
         --diffusion
         --gain
         --gainhf
         --gainlf
         --decaytime
         --decayhflimit
         --decayhfratio
         --decaylfratio
         --reflectionsgain
         --reflectionsdelay
         --reflectionspan
         --latereverbgain
         --latereverbdelay
         --latereverbpan
         --echotime
         --echodepth
         --modtime
         --moddepth
         --airabsorptiongainhf
         --hfreference
         --lfreference
         --roomrollofffactor
      },
   },
   ...
}

resources

local mapinfo = {
   ...
   resources = {
      grassBladeTex = "",
      grassShadingTex = "",
      detailTex = "",
      specularTex = "",
      splatDetailTex = "",
      splatDistrTex = "",
      skyReflectModTex = "",
      detailNormalTex = "",
      lightEmissionTex = "",
   },
   ...
}
grassBladeTex type [string]
Specifies the texture to be used on the grass blades themselves. Green-yellow gradients make for some interesting effects. Defaults to the internally generated blade texture.
grassShadingTex type [string]
Specifies the color variation of the grass across the map. This defaults to the minimap, so the grass color can match the map color.
detailTex type [string]
Specifies the detail texture for the map, for examples and a library, see this sticky thread
specularTex type [string]
?
splatDetailTex type [string]
?
splatDistrTex type [string]
?
skyReflectModTex type [string]
?
detailNormalTex type [string]
?
lightEmissionTex type [string]
?

splats

local mapinfo = {
   ...
   splats = {
      texScales = {0.02, 0.02, 0.02, 0.02},
      texMults  = {1.0, 1.0, 1.0, 1.0},
   },
   ...
}
texScales type [?],[?],[?],[?]
scale value for the splat texture in the RGBA channels respectively.
texMults type [?],[?],[?],[?]
? value for the splat texture in the RGBA channels respectively.

atmosphere

local mapinfo = {
   ...
   atmosphere = {
      minWind      = 5.0,
      maxWind      = 25.0,

      fogStart     = 0.1,
      fogEnd       = 1.0,
      fogColor     = {0.7, 0.7, 0.8},

      sunColor     = {1.0, 1.0, 1.0},
      skyColor     = {0.1, 0.15, 0.7},
      skyDir       = {0.0, 0.0, -1.0},
      skyBox       = "",

      cloudDensity = 0.5,
      cloudColor   = {1.0, 1.0, 1.0},
   },
   ...
}
minWind type [?]
Default: 5.0, The minimum amount of energy the wind on the map will give.
maxWind type [?]
Default: 25, The maximum amount of energy the wind on the map will give.
fogStart type [?]
Default: 0.1, The distance from the camera at which the fog will start.
fogEnd type [?]
Default: ?, ?
fogColor type [0.0-1.0], [0.0-1.0], [0.0-1.0]
Default: {0.7, 0.7, 0.8}, The color of the fog and the infinite plane below the world. The values are in the order Red, Green, Blue. However, giving values higher than 1.0 will give brighter fog and less than 0.0 will give darker.
sunColor type [?],[?],[?]
Default: {1.0, 1.0, 1.0}, The color of the sun in the sky. The values are in the order Red, Green, Blue. This will also effect the size of the star. As the values increase (including over 1.0), the disc will get bigger; the inverse is also true.
skyColor type [?],[?],[?]
Default: {0.1, 0.15, 0.7}, The color of the sky itself. The values are in the order Red, Green, Blue.
skyDir type [?],[?],[?]
Default: {?, ?, ?}, ?
skyBox type [string]
Specify a .dds skybox (also called skycube) for examples and resources see this thread
cloudDensity type [0.0-1.0]
Default: 0.5, The number of clouds in the sky. A percentage in decimal form, 0.0 to 1.0.
cloudColor type [?],[?],[?]
Default: {1.0, 1.0, 1.0}, The color of the clouds. The values are in the order Red, Green, Blue.

grass

local mapinfo = {
   ...
   grass = {
      bladeWaveScale = 1.0,
      bladeWidth  = 0.32,
      bladeHeight = 4.0,
      bladeAngle  = 1.57,
      bladeColor  = {0.59, 0.81, 0.57},
   },
   ...
}
bladeWaveScale type [?]
Default: 1, Specifies how much the wind should effect grass blade movement, as well as the amplitude of the grass motion. Setting it to 0 will stop grass animation.
bladeWidth type [?]
Default: 0.32, Specifies the width of each blade of grass.
bladeHeight type [?]
Default: 4.0, Specifies the length of each blade of grass
bladeAngle type [?]
Default: 1.57, Specifies the curvature of each blade of grass. Unit is radians. 0 means completely straight blades of grass.
bladeColor type [?],[?],[?]
Default: {?, ?, ? }, does nothing when `grassBladeTex` is set

lighting

local mapinfo = {
   ...
   lighting = {
      --// dynsun
      sunStartAngle = 0.0,
      sunOrbitTime  = 1440.0,
      sunDir        = {0.0, 1.0, 2.0, 1e9},

      --// unit & ground lighting
      groundAmbientColor  = {0.5, 0.5, 0.5},
      groundDiffuseColor  = {0.5, 0.5, 0.5},
      groundSpecularColor = {0.1, 0.1, 0.1},
      groundShadowDensity = 0.8,
      unitAmbientColor    = {0.4, 0.4, 0.4},
      unitDiffuseColor    = {0.7, 0.7, 0.7},
      unitSpecularColor   = {0.7, 0.7, 0.7},
      unitShadowDensity   = 0.8,
      
      specularExponent    = 100.0,
   },
   ...
}
sunStartAngle type [?]
Default: ?, ?
sunOrbitTime type [?]
Default: ?, ?
sunDir type [-inf-inf],[-inf-inf],[-inf-inf]
Default: {0.0, 1.0,2.0} , The direction of the sun, which is normalized by Spring. The Y-axis is up.
groundAmbientColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: {0.5,0.5,0.5}, The ambient (non-sun-lit) color of ground, grass, trees and other features. The values are in the order Red, Green, Blue.
groundDiffuseColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: ?, The color of ground where it is fully sun lit (added to GroundAmbientColor). The values are in the order Red, Green, Blue.
groundSpecularColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: {0.1,0.1,0.1}, ? and its effect when a specular map is present?
groundShadowDensity type [?]
Default: 0.8, How far from the non shadowed to the ambient color stuff in shadow will go.
unitAmbientColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: {0.4,0.4,0.4}, The ambient (non-sun-lit) color of units and corpses. The values are in the order Red, Green, Blue.
unitDiffuseColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: ?, The color of units where they is fully sun lit (added to UnitAmbientColor). The color of units where they is fully sun lit (added to UnitAmbientColor). The values are in the order Red, Green, Blue.
unitSpecularColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: {0.7,0.7,0.7}, ?
unitShadowDensity type [?]
Default: 0.8, How far from the non shadowed to the ambient color stuff in shadow will go.
specularExponent type [?]
Default: ?, ?

water

local mapinfo = {
   ...
   water = {
      damage =  0.0,

      repeatX = 0.0,
      repeatY = 0.0,

      absorb    = {0.0, 0.0, 0.0},
      baseColor = {0.0, 0.0, 0.0},
      minColor  = {0.0, 0.0, 0.0},

      ambientFactor  = 1.0,
      diffuseFactor  = 1.0,
      specularFactor = 1.0,
      specularPower  = 20.0,

      planeColor = {0.0, 0.4, 0.0},

      surfaceColor  = {0.75, 0.8, 0.85},
      surfaceAlpha  = 0.55,
      diffuseColor  = {1.0, 1.0, 1.0},
      specularColor = {0.5, 0.5, 0.5},

      fresnelMin   = 0.2,
      fresnelMax   = 0.8,
      fresnelPower = 4.0,

      reflectionDistortion = 1.0,

      blurBase      = 2.0,
      blurExponent = 1.5,

      perlinStartFreq  =  8.0,
      perlinLacunarity = 3.0,
      perlinAmplitude  =  0.9,
      windSpeed = 1.0, --// does nothing yet

      shoreWaves = true,
      forceRendering = false,

      --// undefined == load them from resources.lua!
      --texture =       "",
      --foamTexture =   "",
      --normalTexture = "",
      --caustics = {
      --   "",
      --   "",
      --},

   },
   ...
}
damage type [?]
Default: 0, Number of hit points per game frame (30 frames per second) a unit will be damaged if it is in the water.
repeatX type [?]
Default: ?, effects the filing frequency of the watertexture
repeatY type [?]
Default: ?, effects the filing frequency of the watertexture
absorb type [0.0-1.0],[0.0-1.0],[0.0-1.0],
Default: {0.0, 0.0, 0.0}, How fast different colors (RGB in order) are absorbed by the water. Can be used to make the water look murky at deeper sections and so on. How this works: the waterabsorb value for the color channel gets multiplied by the depth of the water at a point, and this product gets subtracted from WaterBaseColor, until WaterMinColor is reached. Example: WaterAbsorb is 0.01, for the red channel, and we want to know how much red will be left in the water at a Spring elevation of -100, since 0.01*100= 1 , at this depth, there will be no more red component in the water, unless WaterMinColor is higher than 0 on the red channel.
baseColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: {0.0, 0.0, 0.0}, The color of the water just beneath the surface plane. This is the starting color from which deeper waters will absorb more color. The values are in the order Red, Green, Blue.
minColor type [0.0-1.0],[0.0-1.0]
Default: {0.0, 0.0, 0.0}, The smallest values the water will go down to due to WaterAbsorb.
ambientFactor type [?]
Default: ?, ?
diffuseFactor type [?]
Default: ?, ?
specularFactor type [?]
Default: 20, ?
specularPower type [?]
Default: ?, ?
planeColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: {0.0, 0.4, 0.0}, This sets the color of the groundplane under the water outside the map boundaries
surfaceColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: {0.75, 0.8, 0.85}, The color of the water surface. The values are in the order Red, Green, Blue. Mostly affects the colors of the reflections off the top of the water. Has no effect on bump mapped water!
surfaceAlpha type [0.0-1.0]
Default: 0.55, Transparency of the water surface. 0 meaning almost fully transparent water plane(low amount of reflections visible), and 1 being nearly opaque (massive amount of reflections).
diffuseColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: value, This specifies the diffuse color of the water body. WARNING: use of this tag disables the effect of WaterAbsorb , in fact, this tag does nothing but disable WaterAbsorb. Avoid.
specularColor type [0.0-1.0],[0.0-1.0],[0.0-1.0]
Default: {0.5, 0.5, 0.5}, ?
fresnelMin type [?]
Default: 0.2, ?
fresnelMax type [?]
Default: 0.3, ?
fresnelPower type [?]
Default: 4.0, ?
reflectionDistortion type [?]
Default: ?, How much the surface should distort reflections that are cause by waves not being level: ergo it adds more choppyness to your reflections sensible from 0 to 20
blurBase type [?]
Default: ?, Something to do with blur, but it just seems to cause banding with values under 2 and corruption with values above 10
blurExponent type [?]
Default: ?, How much reflections on water surface should be blurred together with the water surface, lower values meaning clearer reflections, (0.2-5) Warning: above 5 seems to cause water corruption
perlinStartFreq type [?]
Default: 8, Wave sizes, smaller = big waves, sensible: [1,20] (influence the wave sizes)
perlinLacunarity type [?]
Default: 3, Defines the size of the perlin waves, small values being big waves ([0.2,5] is sensible)
perlinAmplitude type [?]
Default: 0.9, Base stillness of water surface, 0 is dead still, 1 is 'windy' .This doesnt affect the bump texture depth, besides the fact that this disables the bump texture when set to 0
windSpeed type [?]
Default: ?, does nothing yet
shoreWaves type [0|1]
Default: ?, ?
forceRendering type [0|1]
Default: ?, ?

will have to ask about those undefined tags

teams

local mapinfo = {
   ...
   teams = {
      [0] = {startPos = {x = 2033, z = 852}},
      [1] = {startPos = {x = 10134, z = 852}},
      [2] = {startPos = {x = 0, z = 0}},
      [3] = {startPos = {x = 0, z = 0}},
      ...
   },
   ...
}

Holds an array of start positions

terrainTypes

local mapinfo = {
   ...
   terrainTypes = {
      [0] = {
         name = "Default",
         hardness = 1.0,
         receiveTracks = true,
         moveSpeeds = {
            tank  = 1.0,
            kbot  = 1.0,
            hover = 1.0,
            ship  = 1.0,
         },
      },
      [1]  = { 
         ...
      },
      ...
   },
   ...
}

Holds an array of start types where each element contains:

name type [string]
A label for the terrain type.
hardness type float [0,1]
Default: 1, Used as a multiplier against the mapinfo.mapHardness value. Can be used to make a particular terrain type softer or harder. A value of '1' will make it as hard as MapHardness, and 0.5 will make it half as hard.
receiveTracks type [bool]
Default: 1, Effects whether track decals will be placed on the ground from moving vehicles.
moveSpeeds.tank type float [0-2]
Default: 1, Speed multiplier for tanks when travelling on the parent terrain type. A value of '1' is normal speed, 0.5 will make them travel at half speed on the parent terrain type.
moveSpeeds.kbot type float [0-2]
Default: 1, Speed multiplier for kbots when travelling on the parent terrain type. A value of '1' is normal speed, 0.5 will make them travel at half speed on the parent terrain type.
moveSpeeds.hover type float [0-2]
Default: 1, Speed multiplier for hovercraft when travelling on the parent terrain type. A value of '1' is normal speed, 0.5 will make them travel at half speed on the parent terrain type.
moveSpeeds.ship type float [0-2]
Default: 1, Speed multiplier for ships when travelling on the parent terrain type. A value of '1' is normal speed, 0.5 will make them travel at half speed on the parent terrain type.

custom

local mapinfo = {
   ...
   custom = {
      fog = {
         color    = {0.26, 0.30, 0.41},
         height   = "80%", --// allows either absolue sizes or in percent of map's MaxHeight
         fogatten = 0.003,
      },
      precipitation = {
         density   = 30000,
         size      = 1.5,
         speed     = 50,
         windscale = 1.2,
         texture   = 'LuaGaia/effects/snowflake.png',
      },

   },
   ...
}
variable type [range]
Default: value, text
Retrieved from "https://springrts-wiki.p2004a.com/mediawiki/index.php?title=Mapdev:mapinfo.lua&oldid=13865"