Mapping - Revision history

Nerf cardboard at 11:56, 19 January 2023

2023-01-19T11:56:04Z

← Older revision		Revision as of 11:56, 19 January 2023
Line 1:		Line 1:
	Creating custom maps & mods is explicitly welcomed - Soldat 2 ships with a built in map editor.		Creating custom maps & mods is explicitly welcomed - Soldat 2 ships with a built in map editor.

			[[Category:Modding]]

	== General Tips for Mapping ==		== General Tips for Mapping ==

Nerf cardboard at 01:09, 10 December 2022

2022-12-10T01:09:21Z

← Older revision		Revision as of 01:09, 10 December 2022
Line 3:		Line 3:
	== General Tips for Mapping ==		== General Tips for Mapping ==

	* Make your map ''readable''~~: Follow~~ functional conventions of map design. Steel beams and big bridges are almost always ''collisionmodel: players collide'', while small stairs and platforms are - guess what - ''collisionmodel: platform''. Sandbags and barrels are always ''collisionmodel: bullets collide''.		* Make your map ''readable''; follow functional conventions of map design. Steel beams and big bridges are almost always ''collisionmodel: players collide'', while small stairs and platforms are - guess what - ''collisionmodel: platform''. Sandbags and barrels are always ''collisionmodel: bullets collide''.

	* Especially on CTF maps, make sure to place grenade kits, health packs, and sandbags / barrels, and choose their locations wisely.		* Especially on CTF maps, make sure to place grenade kits, health packs, and sandbags / barrels, and choose their locations wisely.
Line 21:		Line 21:
	* Don't overdo decoration, it will distract too much during game play and in some cases eat FPS of your players. When in doubt, place decorative props on the background layer, so players can hide them via the ''disable detailed backgrounds'' setting.		* Don't overdo decoration, it will distract too much during game play and in some cases eat FPS of your players. When in doubt, place decorative props on the background layer, so players can hide them via the ''disable detailed backgrounds'' setting.

	* There are already a shitload of maps (check out [https://tms2.jrgp.org/ TMS]). If you want to create a map that gets played, make sure you do at least one thing differently. Or fill a niche that ~~is not~~ yet. If you just want to create a piece of art that's of course ~~great too ;)~~		* There are already a shitload of maps (check out [https://tms2.jrgp.org/ TMS]). If you want to create a map that gets played, make sure you do at least one thing differently. Or fill a niche that isn't populated yet. If you just want to create a piece of art that's great too of course


Line 33:		Line 33:
	Maps primarily consist of polygons (''protoshapes''), 3D-props, and spawn locations for various items, and a color scheme.		Maps primarily consist of polygons (''protoshapes''), 3D-props, and spawn locations for various items, and a color scheme.
	Props and protoshapes have attributes that affect their rendering.		Props and protoshapes have attributes that affect their rendering.
	Protoshapes also have a collision model (props don't~~. To~~ make something collide with a prop, draw a protoshape with disabled rendering on top of it.		Protoshapes also have a collision model (props don't - to make something collide with a prop, draw a protoshape with disabled rendering on top of it).
	Maps are persisted to a JSON structure.		Maps are persisted to a JSON structure.

Nerf cardboard at 01:04, 10 December 2022

2022-12-10T01:04:46Z

← Older revision		Revision as of 01:04, 10 December 2022
Line 2:		Line 2:

	== General Tips for Mapping ==		== General Tips for Mapping ==

	* Put work in selecting good colors from the start (see below for a guide to what each color does). This will help a lot getting a good feel for the map.

	* Make your map ''readable'': Follow functional conventions of map design. Steel beams and big bridges are almost always ''collisionmodel: players collide'', while small stairs and platforms are - guess what - ''collisionmodel: platform''. Sandbags and barrels are always ''collisionmodel: bullets collide''.		* Make your map ''readable'': Follow functional conventions of map design. Steel beams and big bridges are almost always ''collisionmodel: players collide'', while small stairs and platforms are - guess what - ''collisionmodel: platform''. Sandbags and barrels are always ''collisionmodel: bullets collide''.
Line 10:		Line 8:

	* Check your map for bad spawn locations in DM - even if it's not a DM map. See section [[#Unwanted Spawn Locations]] for details.		* Check your map for bad spawn locations in DM - even if it's not a DM map. See section [[#Unwanted Spawn Locations]] for details.

			* Put work in selecting good colors from the start (see below for a guide to what each color does). This will help a lot getting a good feel for the map.

	* Always test your maps with the graphics setting ''detailed backgrounds'' set to off. Many people play with this setting (for various reasons), so the map must look okay with this. With this configuration...		* Always test your maps with the graphics setting ''detailed backgrounds'' set to off. Many people play with this setting (for various reasons), so the map must look okay with this. With this configuration...
	** the <code>SkyColor1</code> and <code>SkyColor2</code> colors are not used for the map background. Instead <code>BackDimColor</code> is applied to the background. Make sure it looks OK.		** the <code>SkyColor1</code> and <code>SkyColor2</code> colors are not used for the map background. Instead <code>BackDimColor</code> is applied to the background. Make sure it looks OK.
	** anything in the ''background'' layer is not drawn. Look for map-props that appear floating because they are placed on a ''background'' shape. (To fix this, put these objects also in the ''background'' layer, or move them to a better ~~place'~~		** anything in the ''background'' layer is not drawn. Look for map-props that appear floating because they are placed on a ''background'' shape. To fix this, put these objects also in the ''background'' layer, or move them to a better position.

	* There are already a shitload of maps (check out [https://tms2.jrgp.org/ TMS]. If you want to create a map that gets played, make sure you do at least one thing differently. Or fill a niche that is not yet. If you just want to create a piece of art that's of course great too ;)

	* Add depth to the map by placing objects deep into the foreground and background. ''dm_db_cuba'' is a good example of this.		* Add depth to the map by placing objects deep into the foreground and background. ''dm_db_cuba'' is a good example of this.
Line 22:		Line 20:

	* Don't overdo decoration, it will distract too much during game play and in some cases eat FPS of your players. When in doubt, place decorative props on the background layer, so players can hide them via the ''disable detailed backgrounds'' setting.		* Don't overdo decoration, it will distract too much during game play and in some cases eat FPS of your players. When in doubt, place decorative props on the background layer, so players can hide them via the ''disable detailed backgrounds'' setting.

			* There are already a shitload of maps (check out [https://tms2.jrgp.org/ TMS]). If you want to create a map that gets played, make sure you do at least one thing differently. Or fill a niche that is not yet. If you just want to create a piece of art that's of course great too ;)


	== Built-in Map Editor ==		== Built-in Map Editor ==

	The built-in editor is as of v0.8.46a still ~~in early~~ beta - its UI is quite rough around the edges.		The built-in editor is as of v0.8.46a still very much beta - its UI is quite rough around the edges.
	Here are some tips for working with it.		Here are some tips for working with it.

			=== General Concepts ===

			Maps primarily consist of polygons (''protoshapes''), 3D-props, and spawn locations for various items, and a color scheme.
			Props and protoshapes have attributes that affect their rendering.
			Protoshapes also have a collision model (props don't. To make something collide with a prop, draw a protoshape with disabled rendering on top of it.
			Maps are persisted to a JSON structure.

	=== MapProp & Protoshape Properties ===		=== MapProp & Protoshape Properties ===


	==== Rendering Layer ====		==== Rendering Layer ====

Nerf cardboard at 00:59, 10 December 2022

2022-12-10T00:59:02Z

← Older revision		Revision as of 00:59, 10 December 2022
Line 19:		Line 19:
	* Add depth to the map by placing objects deep into the foreground and background. ''dm_db_cuba'' is a good example of this.		* Add depth to the map by placing objects deep into the foreground and background. ''dm_db_cuba'' is a good example of this.

	* Don't overdo decoration, it will distract too much during game play. When in doubt, place it on the background layer, so players can hide it via the ''disable detailed backgrounds'' setting.		* Most props are 3D - rotating them often gives them quite different appearance and use on the map. Make use of this property to reduce repetition, or to reinterpret what those props represent.

			* Don't overdo decoration, it will distract too much during game play and in some cases eat FPS of your players. When in doubt, place decorative props on the background layer, so players can hide them via the ''disable detailed backgrounds'' setting.

	== Built-in Map Editor ==		== Built-in Map Editor ==
Line 72:		Line 74:

	* '''HueShift''' '''SaturationShift''' '''BrightnessShift''': These transform all colors specified in the settings panel, but does not apply to colors specified on individual map objects.		* '''HueShift''' '''SaturationShift''' '''BrightnessShift''': These transform all colors specified in the settings panel, but does not apply to colors specified on individual map objects.

			==== Sky / Background Colors ====

			* '''SkyColor''', '''SkyColor2''': two colors with a gradient in between can be defined.
			* '''SkyGradientScale''', '''SkyGradientOffset''', '''SkyGradientRotation''': Parameters for the gradient between ''SkyColor'' and ''SkyColor2''.
			* '''BackDimColor''': fallback color for the sky, when the setting ''detailed backgrounds'' is disabled. Note that this also applies a taint on ''background'' objects (why tho?).

	==== Other Colors ====		==== Other Colors ====
Line 78:		Line 86:
	* '''EffectsColor''': Color used to taint stuff like explosions. White == untainted.		* '''EffectsColor''': Color used to taint stuff like explosions. White == untainted.

	===== Protoshapes =====		==== Protoshapes ====

	* '''PlatformsColor''': default color for all ''foreground'' platforms, unless they have an individual color specified.		* '''PlatformsColor''': default color for all ''foreground'' platforms, unless they have an individual color specified.
Line 90:		Line 98:
	** Note: iiuc, this is mostly a relic from the pre-0.8 versions with a different renderer. To me, these settings are of little use for design.		** Note: iiuc, this is mostly a relic from the pre-0.8 versions with a different renderer. To me, these settings are of little use for design.

	====~~= Sky / Background =====~~		==== Miscellaneous ====

	* '''SkyColor''', '''SkyColor2''': two colors with a gradient in between can be defined.
	* '''SkyGradientScale''', '''SkyGradientOffset''', '''SkyGradientRotation''': Parameters for the gradient between ''SkyColor'' and ''SkyColor2''.
	* '''BackDimColor''': fallback color for the sky, when the setting ''detailed backgrounds'' is disabled. Note that this also applies a taint on ''background'' objects (why tho?).

	~~==== Other~~ ====

	* '''Author''': self-explanatory. Make sure to fill this in, people want to be able to find the creator of a map.		* '''Author''': self-explanatory. Make sure to fill this in, people want to be able to find the creator of a map.

Nerf cardboard: add initial mapping guide

2022-12-10T00:54:19Z

add initial mapping guide

New page

Creating custom maps & mods is explicitly welcomed - Soldat 2 ships with a built in map editor.

== General Tips for Mapping ==

* Put work in selecting good colors from the start (see below for a guide to what each color does). This will help a lot getting a good feel for the map.

* Make your map ''readable'': Follow functional conventions of map design. Steel beams and big bridges are almost always ''collisionmodel: players collide'', while small stairs and platforms are - guess what - ''collisionmodel: platform''. Sandbags and barrels are always ''collisionmodel: bullets collide''.

* Especially on CTF maps, make sure to place grenade kits, health packs, and sandbags / barrels, and choose their locations wisely.

* Check your map for bad spawn locations in DM - even if it's not a DM map. See section [[#Unwanted Spawn Locations]] for details.

* Always test your maps with the graphics setting ''detailed backgrounds'' set to off. Many people play with this setting (for various reasons), so the map must look okay with this. With this configuration...
** the <code>SkyColor1</code> and <code>SkyColor2</code> colors are not used for the map background. Instead <code>BackDimColor</code> is applied to the background. Make sure it looks OK.
** anything in the ''background'' layer is not drawn. Look for map-props that appear floating because they are placed on a ''background'' shape. (To fix this, put these objects also in the ''background'' layer, or move them to a better place'

* There are already a shitload of maps (check out [https://tms2.jrgp.org/ TMS]. If you want to create a map that gets played, make sure you do at least one thing differently. Or fill a niche that is not yet. If you just want to create a piece of art that's of course great too ;)

* Add depth to the map by placing objects deep into the foreground and background. ''dm_db_cuba'' is a good example of this.

* Don't overdo decoration, it will distract too much during game play. When in doubt, place it on the background layer, so players can hide it via the ''disable detailed backgrounds'' setting.

== Built-in Map Editor ==

The built-in editor is as of v0.8.46a still in early beta - its UI is quite rough around the edges.
Here are some tips for working with it.

=== MapProp & Protoshape Properties ===

==== Rendering Layer ====

Each object on the map is placed a rendering layer, which affects (a) how it is colored, and (b) sets a default value for the depth / z parameter. Available values are:

* foreground: slightly desaturated, applies ''SunColor'' taint. default for solid protoshapes.
* none: don't draw this object.
* background: desaturates and darkens the object, and applies ''Fog*'' and ''BackDimColor'' taints to it. default for non-colliding protoshapes, which get a different texture applied.
* color: directly applies the color defined on the object 1:1. protoshapes with this also get a different texture.
* original: similar to ''color'', but not the same?
** TODO: whats the difference?

==== Collision Model ====

Applies to Protoshapes only, it's pretty self-explanatory.
Note that platform shapes will always draw a dashed outline, which is good, as it helps with map readability.

==== Material ====

Defines the sound effect when bullets hit this shape. Also applies different bullet ricochet visuals (but those are not actual bullet ricochets able to hit players).

=== Map Settings ===

There are plenty of settings. I highly recommend exploring the entire settings panel, but you can use this section as a guide.

<q>Note that this section does not primarily consist of authoritative information, but is to a large degree reverse 'engineered'.</q>

==== Dimensions & Scaling ====

* ''Width'', ''Height'': Defines the map size

* ''Scale'': This vector does '''not''' scale the whole map (see '''GlobalScale''' for that) - it's a multiplier on the ''Width'' and ''Height'' attributes.

* ''Mirror'': Enable this if you want a symmetrical map. You only draw the left half of the map, and the game generates the other half on the fly. To get a preview, use the ''mirror'' button at the bottom of the settings UI. Individual map objects can be excluded from mirroring via the ''Mirror'' flag.

* ''GlobalScale, GlobalPosition'': These values transform all objects on the map. Do '''not''' set these numbers in the settings panel, but use the ''transform'' button in the map settings panel (the transformation handle UI can appear outside of the map bounds)

==== Lighting ====
* '''SunLightColor''': Sunlight color taints all objects in the ''foreground'' rendering layer.
* '''SunIntensityShift''': The amount of sunlight
* '''SunHorizontalAngle''', '''SunVerticalAngle''': the angle from which light is applied, useful for shadows on protoshape normals.

* '''Fog''', '''FogColor''', '''FogDistance''': fog applies a taint to ''background'' objects, which is applied with increasing opacity with increasing depth (z axis coordinate).

* '''HueShift''' '''SaturationShift''' '''BrightnessShift''': These transform all colors specified in the settings panel, but does not apply to colors specified on individual map objects.

==== Other Colors ====

* '''FadeColor''': Color applied to the area outside of the map boundary.
* '''EffectsColor''': Color used to taint stuff like explosions. White == untainted.

===== Protoshapes =====

* '''PlatformsColor''': default color for all ''foreground'' platforms, unless they have an individual color specified.

* '''BackColor''': default color for all ''background'' platforms, unless they have an individual color specified.

* '''PlatformsTexture''', '''NormalTexture''': defines the texture of the protoshapes and their normals (i.e the depth information that makes them have shadows.
** '''TODO''': is it possible to provide custom textures by placing them next to a map in the <code>Levels/Custom/</code> dir?

* '''DetaulTexture''', '''DetailNormalTexture''', '''DetailTextureScale''', '''DetailNormalTextureScale''', '''DetailImpact''', '''DetailGradientTexture''', '''DetailColor''': Additionally to their primary texture, protoshapes have a detail overlay with a separate set of textures. ''DetailImpact'' scales the visibility of this overlay.
** Note: iiuc, this is mostly a relic from the pre-0.8 versions with a different renderer. To me, these settings are of little use for design.

===== Sky / Background =====

* '''SkyColor''', '''SkyColor2''': two colors with a gradient in between can be defined.
* '''SkyGradientScale''', '''SkyGradientOffset''', '''SkyGradientRotation''': Parameters for the gradient between ''SkyColor'' and ''SkyColor2''.
* '''BackDimColor''': fallback color for the sky, when the setting ''detailed backgrounds'' is disabled. Note that this also applies a taint on ''background'' objects (why tho?).

==== Other ====

* '''Author''': self-explanatory. Make sure to fill this in, people want to be able to find the creator of a map.
* '''AmbientSound''': selects one of a couple soundscapes. there is nothing worse than a sunny map with rumble ambience, be sure to choose a proper ambience.
* '''Generate''': ??? iirc when enabled enabled, some sandbags etc are placed around each basecamp / flag placement.
* '''Seed''': RNG initialization value for the ''generate'' feature.
* '''TopBarrierheight''': ???

=== Workarounds ===

While the editor is in beta, there are plenty of bugs. For many, a workaround is available:

==== Unwanted Spawn Locations ====

In DM, players spawn at random locations on top of any colliding protoshape within map bounds, and not at the spawn locations you can place with the Gostek symbol.
If your map is enclosed by a protoshape that does not extend well outside of the map bounds, players ''will'' spawn there.

This can be avoided, by placing another protoshape along the outer edge of your enclosing shape, extending it well outside of the map bounds.
To not affect your map design you can set apply <code>collision-model: players collide</code> and <code>rendering mode: none</code>.

==== Selecting / moving all map objects ====

It can quickly happen that you run out of space in the left or bottom area.
Instead of moving each object, use the ''transform'' button in the map settings panel to select all objects and move, rotate or scale them all.

==== Protoshape with ''render mode: color'' does not apply color ====

Restart the editor. ¯\_ (ツ)_/¯.

==== Protoshape is invisible ====

This can happen when a shape is very thin or has a very pointy corner.
Moving some vertices around can often fix the issue. If not, creating an extension of the shape

==== Protoshape is always drawn in front of Gosteks ====

The exact root cause is still unclear, some protoshapes just always appear in front of the player, independent of their rendering layer setting and depth value. It could have to do with the vertex order being wrong (clockwise instead of anticlockwise or vice versa). To fix this move some vertexes around, or just replace the shape another with another protoshape that does not have this problem.

== Third Party Tools ==

The community also has written tools for creating maps that integrate with the map game / map editor:

* [https://kreis.uber.space/soldat2/svg2map/ svg2map] by @noerw converts between map JSON files and SVG and can be used to create or edit protoshapes in programs like [https://inkscape.org/ Inkscape].