Difference between revisions of "Maprelease"

From MechWarrior: Living Legends Wiki
Jump to: navigation, search
(→‎Guidelines)
(→‎Folder structure and hierarchy)
 
(30 intermediate revisions by the same user not shown)
Line 1: Line 1:
  
 
= Maprelease =
 
= Maprelease =
 +
 +
The actual release of an map is actually publishing the zipped archive, stripped of any source art, out of performance concern.
 +
It is strongly advised '''not''' to publish the source *.'''cry''' files with the map - they are of non interest to the general player population, hence the longer map download would only hurt the day to day usability of the map.
 +
 +
Sources of the map belong elsewhere - the place for the repository is to be determined yet.
 +
 +
The map folder is to be named preferably with the map release version:
 +
 +
TC_Reference_V1
 +
 +
The map archive is to be named by game type, own name and version tag:
 +
 +
TC_Reference_V1.zip
 +
 +
The same version is to be used in the XML file in the map folder.
 +
 +
/TODO/ explain the fields in the XML file and where they are used and what for.
 +
 +
So it is obvious to the game server administrator, that a newer (or older) map is in question.
 +
 +
----
 +
It seems, the map'''.cry''' file does not have to be named the same as the map-folder, yet it is recommend to be done so.
 +
 +
----
 +
So far there are following map types:
 +
TC (terrain control), TSA (Team Solaris arena - test of strength), SA (Solaris arena - all vs all)
 +
And the multiplayer map folders are organized accordingly
 +
 +
----
 +
Once a map has been finished, and it's layout is fixed and known, the map-loading image is to be defined.
 +
 +
Either ''do it good''(tm) or do it ''the same'' - i.e. follow the already existing maps art. The file itself is to be of '''DDS''' format and to be placed alongside the XML where it is referred to by an arbitrary name.
 +
 +
----
 +
It is customary to have an text on top of the screen providing a background story and an graph/text section providing info of the allowed assets (ground, mech, ASF, VTOL). But there are known (and liked!) exceptions to this. Maps should either comply to the [[Gameflow]] guidelines or to reflect an apocryphal BT historical battle.
 +
 +
----
 +
/TODO --update broken links/
 +
 +
<--https://shadowlegion.tk/mwll/tools/MWLLHasher.exe MWLL Hasher-->
 +
 +
this is an easy tool you can use in order to generate a manifest for the map (filelist.xml). This is used by the map autodownloader so it can check the downloaded map.
 +
 +
How to use it:
 +
- Export the map to the directory it's gonna be run from (e.g. Levels/Multiplayer/TC/TC_Foo_V01)
 +
- Remove unnecessary files (e.g. cry source file)
 +
- Run the tool, click on Browse and select that directory
 +
- Click on Generate Manifest, then click on Save Manifest. Just save it in the same path where the map is saved(edited)
 +
  
 
== Release stages ==
 
== Release stages ==
−
Releasing a map is essentially providing public access to it. To release a map we have two actual stages.
+
Releasing a map is essentially providing public access to it. A map can have up to three release stages. Here we assume that any map has undergone basic testing on a clean MW:LL installation, loads without issues and players who have a copy connect to it without any issues as well.
−
 
 
  
 
=== Testing Release ===
 
=== Testing Release ===
 
For a map to be considered ''released'' for testing it has to be publicly accessible to, at least, the test players, if not everyone.<br>
 
For a map to be considered ''released'' for testing it has to be publicly accessible to, at least, the test players, if not everyone.<br>
 
For this to be the case the map is usually uploaded to a public storage service and the link is to be posted on our forum or Discord.<br>
 
For this to be the case the map is usually uploaded to a public storage service and the link is to be posted on our forum or Discord.<br>
−
However, for the map to be acceptable to be spun on an community server, there are a few guidelines to be followed. Those assure the process is as streamlined and stress free for all the parties involved.
+
However, for the map to be acceptable for a spin on a community server, there are few guidelines to be followed. Those assure the process is as streamlined and stress free for all the parties involved.
−
 
 
  
 
=== Public Gaming release ===
 
=== Public Gaming release ===
Line 19: Line 66:
 
If an map shows outstanding performance or holds essential assets to the game (or both preferably) the map can undergo ''being endorsed'' to the MW:LL release.<br>
 
If an map shows outstanding performance or holds essential assets to the game (or both preferably) the map can undergo ''being endorsed'' to the MW:LL release.<br>
 
Further constraints might ensue then. Details are to be determined, by the developer team in this case.
 
Further constraints might ensue then. Details are to be determined, by the developer team in this case.
−
 
  
 
== Guidelines ==
 
== Guidelines ==
Line 25: Line 71:
  
 
=== Naming conventions ===
 
=== Naming conventions ===
−
There is no co-relation of the map's cry file and the map folder whatsoever. Yet, it is highly recommended to name those two the same, as well as the accompanying XML file. To avoid any undue confusion down the road. (And it's an long road note that.)<br>
+
There is no co-relation of the map's cry file and the map folder whatsoever. Yet, it is highly recommended to name those two the same, as well as the accompanying XML file. To avoid any undue confusion down the road. (And it's an long road - note that.)<br>
 +
A common cause of failing to load a map is if the XML ''manifest'' file is not the same as the folder.
 
It is customary to version the ''community'' maps so it is ''loud and clear'' which map is older and what archive it's coming from.
 
It is customary to version the ''community'' maps so it is ''loud and clear'' which map is older and what archive it's coming from.
 
The versioning process is somewhat meticulous and arduous, but we have a most streamlined guide for it below.
 
The versioning process is somewhat meticulous and arduous, but we have a most streamlined guide for it below.
  
 
=== Folder structure and hierarchy ===
 
=== Folder structure and hierarchy ===
−
It is advised to follow the folder structure from the first steps in the Sandbox2 editor all the way - they are not that cumbersome  - but once accustomed to them may a headache will be saved later.<br>
+
It is advised to obey the [[folderstructure|folder structure]] from the first steps in the Sandbox2 editor all the way - they are not that cumbersome  - but once accustomed to them many a headache will be saved later on.<br>
−
[[File:Map-File-structure.png|right]]
+
[[File:Map-File-structure.png]]<br>
 
Notice the ''redundant path component'' "'''Multiplayer\TC\''' that occur twice :
 
Notice the ''redundant path component'' "'''Multiplayer\TC\''' that occur twice :
 
This provides for two goals:<br>
 
This provides for two goals:<br>
 
# To remain able to work on more maps while releasing one then the other.
 
# To remain able to work on more maps while releasing one then the other.
 
# To be able to keep the map in the '''Mods/MWLL/Game/Levels/Multiplayer/''' file tree - where it belongs.
 
# To be able to keep the map in the '''Mods/MWLL/Game/Levels/Multiplayer/''' file tree - where it belongs.
 +
Having the map edited in it's native ''file tree position'' further simplifies the version transition, and evades some of the issues during deploying the map.
 
<br>
 
<br>
−
To zip this up:<br>
+
To zip a map up:<br>
−
# just select the last '''Multiplayer''' folder and zip it up.
+
# move the map folder that's ready to be released to the 2nd ''nested'' '''Multiplayer\TC\'''.
 +
# prune all the sandbox content leaving only the play files - as shown on the image<br>
 +
[[File:Released-map.png|332px]]
 +
# just select the last ''nested'' '''Multiplayer''' folder and zip it up.
 
# rename the archive to the exact map folder name - '''TC_Warresst_R6.zip''' in our example.
 
# rename the archive to the exact map folder name - '''TC_Warresst_R6.zip''' in our example.
 
<br>
 
<br>
 
This way you assure your published map will ''automagically'' land in the players folder when auto-downloaded from the map repository once it's hosted there.
 
This way you assure your published map will ''automagically'' land in the players folder when auto-downloaded from the map repository once it's hosted there.
 +
 +
=== Release Version Increment ===
 +
It is normal that a map changes version over the course of its lifetime. It is moreover desirable the maps folder name reflect this. The same goes for the zip archive the map is published in. Here we describe in detail the smoothest transition between adjacent map versions. The change is best to be applied ''before'' and further work on the map version has been done.<br>
 +
Prerequisites (apps used):
 +
# 7zip file manager (part of the 7zip free download)
 +
# WinRAR (trial ware file manager)
 +
# Geany (free GPL licensed advanced code editor/IDE)
 +
<br>
 +
1. begin by 7z-ipping the sources and the whole folder in the TC or TSA branch. To have a point of return should anything go ''bork''.<br>
 +
[[File:1._7zip-file-manager.png|600px]]<br>
 +
2. Rename the folder to reflect the increment of the release.<br>
 +
[[File:2._renaming.png]]<br>
 +
3. Proceed with renaming the files inside the folder
 +
<br>[[File:3._more-renaming.png]]<br>
 +
4. rename the cry file to associate it with WinRAR as shown
 +
<br>[[File:4._prepare-for-winzip.png]]<br>
 +
5. once opened, double click the '''level.editor_xml''' - at first you will be prompted to ''associate it''. Do so for your favorite advanced text editor (mine is '''Geany''')
 +
<br>[[File:5._open-with-winRAR.png|600px]]<br>
 +
6. in the file, ''seek and replace'' ([ctrl]+[h] in Geany) all the references from to old folder name to the updated one. Geany does that on single click.
 +
<br>[[File:6._edit-with-associated-advanced-editor.png|600px]]<br>
 +
7. this can be used also for endorsing alien art into a map. Once all is updated, save the file and exit the editor. When prompted to update the zip archive - allow for it.
 +
<br>[[File:7._save-and-update-archive.png|600px]]<br>
 +
8. remember to restore back all the extensions you changed. Check twice.
 +
<br>[[File:8._restore-extension.png]]<br>
 +
9. update the maps XML file as well ('''Display Name''' field will be shown ''in game'' on the server browser) [[File:9._update-XML.png|600px]]<br>
 +
10. Find and and open all the material files in the map folder at once in the advanced editor (drag and drop works really well for this)
 +
<br>[[File:10._mass-open-all-mtl-files.png]]<br>
 +
11. Seek and update all the references to point to the just updated folder name (in session means in all currently open files)
 +
<br>[[File:11._rename-all-instances.png|600px]]<br>
 +
12. It goes without saying - all files are to be saved - '''Geany''' has ''save all'' icon handy.
 +
<br>[[File:12._save-all-files.png|600px]]<br>
 +
13. The final test is the '''Sandbox 2''' editor - open it and load the newly renamed map.
 +
<br>[[File:13._run-check-in-sandbox2.png|600px]]<br>
 +
Now on you are ready to work on and apply the further tweaks and modifications to the map - and then release it afterward.

Latest revision as of 18:03, 18 August 2019

Maprelease

The actual release of an map is actually publishing the zipped archive, stripped of any source art, out of performance concern. It is strongly advised not to publish the source *.cry files with the map - they are of non interest to the general player population, hence the longer map download would only hurt the day to day usability of the map.

Sources of the map belong elsewhere - the place for the repository is to be determined yet.

The map folder is to be named preferably with the map release version: 

TC_Reference_V1

The map archive is to be named by game type, own name and version tag: 

TC_Reference_V1.zip

The same version is to be used in the XML file in the map folder.

/TODO/ explain the fields in the XML file and where they are used and what for.

So it is obvious to the game server administrator, that a newer (or older) map is in question.

It seems, the map.cry file does not have to be named the same as the map-folder, yet it is recommend to be done so.

So far there are following map types: 

TC (terrain control), TSA (Team Solaris arena - test of strength), SA (Solaris arena - all vs all)

And the multiplayer map folders are organized accordingly

Once a map has been finished, and it's layout is fixed and known, the map-loading image is to be defined.

Either do it good(tm) or do it the same - i.e. follow the already existing maps art. The file itself is to be of DDS format and to be placed alongside the XML where it is referred to by an arbitrary name.

It is customary to have an text on top of the screen providing a background story and an graph/text section providing info of the allowed assets (ground, mech, ASF, VTOL). But there are known (and liked!) exceptions to this. Maps should either comply to the Gameflow guidelines or to reflect an apocryphal BT historical battle.

/TODO --update broken links/

<--https://shadowlegion.tk/mwll/tools/MWLLHasher.exe MWLL Hasher-->

this is an easy tool you can use in order to generate a manifest for the map (filelist.xml). This is used by the map autodownloader so it can check the downloaded map.

How to use it: - Export the map to the directory it's gonna be run from (e.g. Levels/Multiplayer/TC/TC_Foo_V01) - Remove unnecessary files (e.g. cry source file) - Run the tool, click on Browse and select that directory - Click on Generate Manifest, then click on Save Manifest. Just save it in the same path where the map is saved(edited)


Release stages

Releasing a map is essentially providing public access to it. A map can have up to three release stages. Here we assume that any map has undergone basic testing on a clean MW:LL installation, loads without issues and players who have a copy connect to it without any issues as well.

Testing Release

For a map to be considered released for testing it has to be publicly accessible to, at least, the test players, if not everyone.
For this to be the case the map is usually uploaded to a public storage service and the link is to be posted on our forum or Discord.
However, for the map to be acceptable for a spin on a community server, there are few guidelines to be followed. Those assure the process is as streamlined and stress free for all the parties involved.

Public Gaming release

For a map to be considered public it has to be present on the repositories for automatic map download.
Being clear of test release, we assume the map already conforms to the release guidelines.

Endorsed Maps

If an map shows outstanding performance or holds essential assets to the game (or both preferably) the map can undergo being endorsed to the MW:LL release.
Further constraints might ensue then. Details are to be determined, by the developer team in this case.

Guidelines

First of all the map is to be an authors work, and if it's derived work, the due credit is to be shown.

Naming conventions

There is no co-relation of the map's cry file and the map folder whatsoever. Yet, it is highly recommended to name those two the same, as well as the accompanying XML file. To avoid any undue confusion down the road. (And it's an long road - note that.)

A common cause of failing to load a map is if the XML manifest file is not the same as the folder.

It is customary to version the community maps so it is loud and clear which map is older and what archive it's coming from. The versioning process is somewhat meticulous and arduous, but we have a most streamlined guide for it below.

Folder structure and hierarchy

It is advised to obey the folder structure from the first steps in the Sandbox2 editor all the way - they are not that cumbersome - but once accustomed to them many a headache will be saved later on.
Map-File-structure.png
Notice the redundant path component "Multiplayer\TC\ that occur twice : This provides for two goals:

  1. To remain able to work on more maps while releasing one then the other.
  2. To be able to keep the map in the Mods/MWLL/Game/Levels/Multiplayer/ file tree - where it belongs.
Having the map edited in it's native file tree position further simplifies the version transition, and evades some of the issues during deploying the map.


To zip a map up:

  1. move the map folder that's ready to be released to the 2nd nested Multiplayer\TC\.
  2. prune all the sandbox content leaving only the play files - as shown on the image

Released-map.png

  1. just select the last nested Multiplayer folder and zip it up.
  2. rename the archive to the exact map folder name - TC_Warresst_R6.zip in our example.


This way you assure your published map will automagically land in the players folder when auto-downloaded from the map repository once it's hosted there.

Release Version Increment

It is normal that a map changes version over the course of its lifetime. It is moreover desirable the maps folder name reflect this. The same goes for the zip archive the map is published in. Here we describe in detail the smoothest transition between adjacent map versions. The change is best to be applied before and further work on the map version has been done.
Prerequisites (apps used):

  1. 7zip file manager (part of the 7zip free download)
  2. WinRAR (trial ware file manager)
  3. Geany (free GPL licensed advanced code editor/IDE)


1. begin by 7z-ipping the sources and the whole folder in the TC or TSA branch. To have a point of return should anything go bork.
1. 7zip-file-manager.png
2. Rename the folder to reflect the increment of the release.
2. renaming.png
3. Proceed with renaming the files inside the folder
3. more-renaming.png
4. rename the cry file to associate it with WinRAR as shown
4. prepare-for-winzip.png
5. once opened, double click the level.editor_xml - at first you will be prompted to associate it. Do so for your favorite advanced text editor (mine is Geany)
5. open-with-winRAR.png
6. in the file, seek and replace ([ctrl]+[h] in Geany) all the references from to old folder name to the updated one. Geany does that on single click.
6. edit-with-associated-advanced-editor.png
7. this can be used also for endorsing alien art into a map. Once all is updated, save the file and exit the editor. When prompted to update the zip archive - allow for it.
7. save-and-update-archive.png
8. remember to restore back all the extensions you changed. Check twice.
8. restore-extension.png
9. update the maps XML file as well (Display Name field will be shown in game on the server browser) 9. update-XML.png
10. Find and and open all the material files in the map folder at once in the advanced editor (drag and drop works really well for this)
10. mass-open-all-mtl-files.png
11. Seek and update all the references to point to the just updated folder name (in session means in all currently open files)
11. rename-all-instances.png
12. It goes without saying - all files are to be saved - Geany has save all icon handy.
12. save-all-files.png
13. The final test is the Sandbox 2 editor - open it and load the newly renamed map.
13. run-check-in-sandbox2.png
Now on you are ready to work on and apply the further tweaks and modifications to the map - and then release it afterward.

Retrieved from "https://wiki.mechlivinglegends.net/index.php?title=Maprelease&oldid=7834"