Extra tools: Difference between revisions

From DDraceNetwork
← Older edit
VisualWikitext
"Remove LangNavBox"
Rafaelff (talk | contribs)
Automoderated users, translator-mod
550 edits
Remove "version" from DDNet version X.x to uniformize
 
(12 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<languages />
<translate>
<!--T:1-->
'''''Extra tools''''' are available for running some non-gaming-related tasks, like map optimization by mappers, or debugging and testing by developers. These tools must be run from command-line interface (e.g. Command Prompt on Windows or Terminal on Linux) either by adding their containing directory to the PATH variable or by running directly from the containing directory.
'''''Extra tools''''' are available for running some non-gaming-related tasks, like map optimization by mappers, or debugging and testing by developers. These tools must be run from command-line interface (e.g. Command Prompt on Windows or Terminal on Linux) either by adding their containing directory to the PATH variable or by running directly from the containing directory.


== Getting the extra tools ==
==Getting the extra tools== <!--T:2-->


<!--T:3-->
These tools are '''not''' provided in the binary DDNet game in the [https://ddnet.org/downloads/ Downloads page]. Having that said, extra tools mapping-related can be download for different platforms in the Downloads page, under the name "Graphics Tools".
These tools are '''not''' provided in the binary DDNet game in the [https://ddnet.org/downloads/ Downloads page]. Having that said, extra tools mapping-related can be download for different platforms in the Downloads page, under the name "Graphics Tools".


<!--T:4-->
These and other extra tools (listed below) can be found on the [https://github.com/ddnet/ddnet DDNet source code] under [https://github.com/ddnet/ddnet/tree/master/src/tools src/tools] directory.
These and other extra tools (listed below) can be found on the [https://github.com/ddnet/ddnet DDNet source code] under [https://github.com/ddnet/ddnet/tree/master/src/tools src/tools] directory.


== List of extra tools ==
==List of extra tools== <!--T:5-->


<!--T:6-->
See below the list and description of the tools.
See below the list and description of the tools.


=== config_retrieve ===
===config_retrieve=== <!--T:7-->


  config_retrieve ''map_file''
<!--T:8-->
config_retrieve ''map_file''


<!--T:9-->
Retrieves configuration embedded in a DDNet map file ''map_file'' and stores it in a DDNet map configuration file with same filename (e.g. "Kobra 4.map" returns "Kobra 4.cfg")
Retrieves configuration embedded in a DDNet map file ''map_file'' and stores it in a DDNet map configuration file with same filename (e.g. "Kobra 4.map" returns "Kobra 4.cfg")


<!--T:10-->
''Available since: DDNet 9.0''
''Available since: DDNet 9.0''


=== config_store ===
===config_store=== <!--T:11-->


  config_store ''map_file''
<!--T:12-->
config_store ''map_file''


<!--T:13-->
Stores configuration from a map's configuration file into the ''map_file''.  Both configuration and map files must have the same filename in the same directory, otherwise the operation will fail.
Stores configuration from a map's configuration file into the ''map_file''.  Both configuration and map files must have the same filename in the same directory, otherwise the operation will fail.


<!--T:14-->
If there is no difference between the configuration to stored and the configuration embedded in the map, then operation will be canceled with message <code>configs coincide, not updating map</code>.
If there is no difference between the configuration to stored and the configuration embedded in the map, then operation will be canceled with message <code>configs coincide, not updating map</code>.


<!--T:15-->
''Available since: DDNet 9.0''
''Available since: DDNet 9.0''


=== crapnet ===
===crapnet=== <!--T:16-->


  crapnet
<!--T:17-->
crapnet


<!--T:18-->
Tests connection by setting a client–server connection locally and running ping between them. Reports dropped packets with message <code>dropped packet</code> and successes with <code>cfg = ''number''</code>, where ''number'' varies from 0 to 2.
Tests connection by setting a client–server connection locally and running ping between them. Reports dropped packets with message <code>dropped packet</code> and successes with <code>cfg = ''number''</code>, where ''number'' varies from 0 to 2.


=== dilate ===
===demo_extract_chat=== <!--T:19-->
 
<!--T:20-->
demo_extract_chat ''demo_file''
 
<!--T:21-->
Exports all messages from a demo file, output is printed to the console.
 
<!--T:22-->
chat: *** 'nameless tee' entered and joined the game
chat: nameless tee: Hello!
broadcast: Welcome!
teamchat: brainless tee: Hello team!
whisper: -> nameless tee: Hi!
 
<!--T:23-->
''Available since: DDNet 17.4''
 
===dilate=== <!--T:24-->


  dilate ''image_file1'' [''image_file2'' ... ]
<!--T:25-->
dilate ''image_file1'' [''image_file2'' ... ]


<!--T:26-->
It is a graphics tool, mainly useful for mappers. It takes care of transparent areas to prevent black/white outlines around your images ingame, therefore avoiding blending and mipmap issues. See [http://wiki.polycount.com/wiki/Edge_padding Edge padding] for more info.
It is a graphics tool, mainly useful for mappers. It takes care of transparent areas to prevent black/white outlines around your images ingame, therefore avoiding blending and mipmap issues. See [http://wiki.polycount.com/wiki/Edge_padding Edge padding] for more info.


<!--T:27-->
Note this works only in RGBA image files (e.g. PNG files). So, it will fail in e.g. JPEG files.
Note this works only in RGBA image files (e.g. PNG files). So, it will fail in e.g. JPEG files.


=== dummy_map ===
===dummy_map=== <!--T:28-->
 
<!--T:29-->
dummy_map
 
<!--T:30-->
Creates a dummy, small empty map used for vanilla antispoof (<code>sv_vanilla_antispoof</code>). See [https://github.com/ddnet/ddnet/blob/a66379918832e5ad93332bbe0475394b156b5c24/src/engine/shared/network_server.cpp#L371] for more info.
 
===map_convert_07=== <!--T:31-->
 
<!--T:32-->
map_convert_07 ''src_map_file'' ''dest_map_file''
 
<!--T:33-->
Makes <code>''dest_map_file''</code> compatible with Teeworlds version 7.x that otherwise it would be compatible '''only''' with Teeworlds version 6.x. If successfully, it creates a valid 07-compatible destination map; otherwise, it returns one of the following:
 
<!--T:34-->
*an usage message if incorrect arguments are provided
*<code>failed to open source map</code> if an error happens when opening the source map
*<code>failed to open destination map</code> if an error happens when opening the destination map
*<code>error loading storage</code> if failed to open storage for some reason
*<code>failed to open image file</code> if error happens on opening PNG image
*<code>invalid image format</code> if incorrectly formatted PNG.


  dummy_map
<!--T:35-->
''Available since: DDNet 12.9''


Creates a dummy, small empty map to be used to start a server. See [https://github.com/ddnet/ddnet/blob/a66379918832e5ad93332bbe0475394b156b5c24/src/engine/shared/network_server.cpp#L371] for more info.
===map_create_pixelart=== <!--T:36-->


=== fake_server ===
<!--T:37-->
map_create_pixelart <image.png> <img_pixelsize> <input_map> <layergroup_id> <layer_id> <pos_x> <pos_y> <quad_pixelsize> <output_map> [optimize=0|1] [centralize=0|1]


  fake_server
<!--T:38-->
Creates a map with quad-based pixelart from an image.


Creates a fake server for testing.
<!--T:39-->
Note: use destination layer tiles as a reference for positions and pixels for sizes.


=== map_convert_07 ===
<!--T:40-->
Note: set img_pixelsize to 0 to consider the largest possible size.


  map_convert_07 ''src_map_file'' ''dest_map_file''
<!--T:41-->
Note: set quad_pixelsize to 0 to consider the same value of img_pixelsize.


Makes <code>''dest_map_file''</code> compatible with Teeworlds version 7.x that otherwise it would be compatible '''only''' with Teeworlds version 6.x. If successfully, it creates a valid 07-compatible destination map; otherwise, it returns one of the following:
<!--T:42-->
Note: if image.png has not a perfect pixelart grid, result might be unexpected, manually fix img_pixelsize to get it better.


* an usage message if incorrect arguments are provided
<!--T:43-->
* <code>failed to open source map</code> if an error happens when opening the source map
Options: optimize tries to reduce the total number of quads (default: 1).
* <code>failed to open destination map</code> if an error happens when opening the destination map
* <code>error loading storage</code> if failed to open storage for some reason
* <code>failed to open image file</code> if error happens on opening PNG image
* <code>invalid image format</code> if incorrectly formatted PNG.


''Available since: DDNet 12.9''
<!--T:44-->
Options: centralize places all pivots at the same position (default: 0).


=== map_diff ===
===map_diff=== <!--T:45-->


  map_diff ''map_file1'' ''map_file2''
<!--T:46-->
map_diff ''map_file1'' ''map_file2''


<!--T:47-->
Compares two map files, reporting one of the follow:
Compares two map files, reporting one of the follow:
* no diff output, meaning the maps are the same
*no diff output, meaning the maps are the same
* <code>different layer numbers</code>, if one map has more layers than another
*<code>different layer numbers</code>, if one map has more layers than another
* <code>different tile layers</code>, if the number of layers is the same, but at least one layer is different
*<code>different tile layers</code>, if the number of layers is the same, but at least one layer is different
* lastly, the index and flags positions that differ.
*lastly, the index and flags positions that differ.


<!--T:48-->
If there is no difference between maps, returns 0; otherwise, returns 1.
If there is no difference between maps, returns 0; otherwise, returns 1.


=== map_extract ===
===map_extract=== <!--T:49-->


  map_extract ''map_file'' [''directory'']
<!--T:50-->
map_extract ''map_file'' [''directory'']


<!--T:51-->
Extracts contents from ''map_file'' into the ''directory''. If optional argument ''directory'' is not provided, extracts to the current directory.
Extracts contents from ''map_file'' into the ''directory''. If optional argument ''directory'' is not provided, extracts to the current directory.


=== map_optimize ===
===map_find_env=== <!--T:52-->


  map_optimize ''source_map_filepath'' [''dest_map_filepath'']
<!--T:53-->
map_find_env <input_map> <env_number>


<!--T:54-->
Finds quads using a specific envelope and prints their index and position to the console.
<!--T:55-->
Note: returned quads positions are relative to their layers.
===map_optimize=== <!--T:56-->
<!--T:57-->
map_optimize ''source_map_filepath'' [''dest_map_filepath'']
<!--T:58-->
Optimizes the map file in the <code>''source_map_filepath''</code> given (see [https://github.com/ddnet/ddnet/pull/3201 how it works]) and stores the output in the given <code>''dest_map_filepath''</code>; if <code>''dest_map_filepath''</code> is unset, output path defaults to <code>out/''source_map_filename''.map</code>, stripping the path and the extension of the source file.
Optimizes the map file in the <code>''source_map_filepath''</code> given (see [https://github.com/ddnet/ddnet/pull/3201 how it works]) and stores the output in the given <code>''dest_map_filepath''</code>; if <code>''dest_map_filepath''</code> is unset, output path defaults to <code>out/''source_map_filename''.map</code>, stripping the path and the extension of the source file.


<!--T:59-->
Note the name of the embedded images optimized is changed from <code>''originalname''</code> to <code>''originalname''_cut_''newSHA256''</code> (where <code>''newSHA256''</code> is the new sha256 of the embedded optimized image). It is renamed is to make clear it was optimized because this tool '''will''' make changes in the mapres used by the map file.
Note the name of the embedded images optimized is changed from <code>''originalname''</code> to <code>''originalname''_cut_''newSHA256''</code> (where <code>''newSHA256''</code> is the new sha256 of the embedded optimized image). It is renamed is to make clear it was optimized because this tool '''will''' make changes in the mapres used by the map file.


<!--T:60-->
If failed to open source or target file, returns -1.
If failed to open source or target file, returns -1.


<!--T:61-->
''Available since:'' DDNet 15.5.4
''Available since:'' DDNet 15.5.4


=== map_replace_image ===
===map_replace_area=== <!--T:62-->
 
<!--T:63-->
map_replace_area <from_map> <from_x> <from_y> <to_map> <to_x> <to_y> <width> <height> <output_map>
 
<!--T:64-->
Replaces an area of one map with an area from another map.
 
<!--T:65-->
Note: use game layer tiles as a reference for both coordinates and sizes.


  map_replace_image ''map_file1'' ''map_file2'' ''imagename'' ''image_file''
===map_replace_image=== <!--T:66-->


<!--T:67-->
map_replace_image ''map_file1'' ''map_file2'' ''imagename'' ''image_file''
<!--T:68-->
Replaces the image ''imagename'' currently inside the map filename ''map_file1'' with the image filepath ''image_file'', and save into the map filename ''map_file2.map''.
Replaces the image ''imagename'' currently inside the map filename ''map_file1'' with the image filepath ''image_file'', and save into the map filename ''map_file2.map''.


<!--T:69-->
Please note:
Please note:
* Both map filenames must be relative to user default DDNet folder
*Both map filenames must be relative to user default DDNet folder
* New image filepath can be absolute, or relative to the current directory
*New image filepath can be absolute, or relative to the current directory


=== map_resave ===
===map_resave=== <!--T:70-->


  map_resave ''map_file'' ''image_file''
<!--T:71-->
map_resave ''source_map.map'' ''destination_map.map''


Updates the map file ''map_file.map'' with the provided file ''image_file''.
<!--T:72-->
Reads the map ''source_map.map'' and writes it back to ''destination_map.map'' using the latest map format.


The error status 255 is returned if 1) a number of arguments different from 2 is provided, 2) if the ''map_file.map'' is not valid, or 3) if ''image_file'' is not a valid image file (e.g. it is a text file); otherwise, return 0.
===packetgen=== <!--T:73-->


=== packetgen ===
<!--T:74-->
packetgen


  packetgen
<!--T:75-->
Generates and sends network packets to 127.0.0.1:8303 (localhost, in default server port) to test communication with a local server instance.
 
===stun=== <!--T:76-->
 
<!--T:77-->
stun ''address''


Generates and sends network packets to 127.0.0.1:8303 (localhost, in default server port) to test communication with a local server instance.
<!--T:78-->
Sends [[wikipedia:STUN|STUN]] request to server and checks response.
 
===twping=== <!--T:79-->
 
<!--T:80-->
twping ''server''[:''port'']
 
<!--T:81-->
Measures ping to a teeworlds server by requesting the server information. ''port'' defaults to 8303.


=== unicode_confusables ===
===unicode_confusables=== <!--T:82-->


  unicode_confusables ''string1'' ''string2''
<!--T:83-->
unicode_confusables ''string1'' ''string2''


<!--T:84-->
Compares ''string1'' with ''string2'' and report if they are "confusable", i.e. if the characters are "equal" and could cause confusion. For this to work, the characters with accents or other things around them are considered the "confusable" with the base character. Therefore, ''aa'' and ''aá'' are confusable (''á'' was considered as ''a''), while ''aa'' and ''ab'' are not.
Compares ''string1'' with ''string2'' and report if they are "confusable", i.e. if the characters are "equal" and could cause confusion. For this to work, the characters with accents or other things around them are considered the "confusable" with the base character. Therefore, ''aa'' and ''aá'' are confusable (''á'' was considered as ''a''), while ''aa'' and ''ab'' are not.


<!--T:85-->
If they are confusable, it returns <code>not_confusable=0</code>, otherwise, returns <code>not_confusable=1</code>.
If they are confusable, it returns <code>not_confusable=0</code>, otherwise, returns <code>not_confusable=1</code>.


''Available since: DDNet version 10.3.5''
<!--T:86-->
''Available since: DDNet 10.3.5''


''New in DDNet version 12.9:'' Unicode 12.0 support and the tool name was renamed from ''confusables'' to ''unicode_confusables''.
<!--T:87-->
''New in DDNet 12.9:'' Unicode 12.0 support and the tool name was renamed from ''confusables'' to ''unicode_confusables''.


=== uuid ===
===uuid=== <!--T:88-->


  uuid ''name''
<!--T:89-->
uuid ''name''


<!--T:90-->
Prints uuid for the provided ''name''.
Prints uuid for the provided ''name''.


<!--T:91-->
The uuid system was implemented to be easily extended by independent authors without collisions, something that the old system – with increasing integers – did not allow. This works for engine and game messages, snapshot items and events.
The uuid system was implemented to be easily extended by independent authors without collisions, something that the old system – with increasing integers – did not allow. This works for engine and game messages, snapshot items and events.


<!--T:92-->
Exits with error status 255 if ''name'' is not provided.
Exits with error status 255 if ''name'' is not provided.


<!--T:93-->
''Available since: DDNet 10.6.1''
''Available since: DDNet 10.6.1''
</translate>

Latest revision as of 17:23, 9 February 2024

Other languages:

Extra tools are available for running some non-gaming-related tasks, like map optimization by mappers, or debugging and testing by developers. These tools must be run from command-line interface (e.g. Command Prompt on Windows or Terminal on Linux) either by adding their containing directory to the PATH variable or by running directly from the containing directory.

Getting the extra tools

These tools are not provided in the binary DDNet game in the Downloads page. Having that said, extra tools mapping-related can be download for different platforms in the Downloads page, under the name "Graphics Tools".

These and other extra tools (listed below) can be found on the DDNet source code under src/tools directory.

List of extra tools

See below the list and description of the tools.

config_retrieve

config_retrieve map_file

Retrieves configuration embedded in a DDNet map file map_file and stores it in a DDNet map configuration file with same filename (e.g. "Kobra 4.map" returns "Kobra 4.cfg")

Available since: DDNet 9.0

config_store

config_store map_file

Stores configuration from a map's configuration file into the map_file. Both configuration and map files must have the same filename in the same directory, otherwise the operation will fail.

If there is no difference between the configuration to stored and the configuration embedded in the map, then operation will be canceled with message configs coincide, not updating map.

Available since: DDNet 9.0

crapnet

crapnet

Tests connection by setting a client–server connection locally and running ping between them. Reports dropped packets with message dropped packet and successes with cfg = number, where number varies from 0 to 2.

demo_extract_chat

demo_extract_chat demo_file

Exports all messages from a demo file, output is printed to the console. 

chat: *** 'nameless tee' entered and joined the game
chat: nameless tee: Hello!
broadcast: Welcome!
teamchat: brainless tee: Hello team!
whisper: -> nameless tee: Hi!

Available since: DDNet 17.4

dilate

dilate image_file1 [image_file2 ... ]

It is a graphics tool, mainly useful for mappers. It takes care of transparent areas to prevent black/white outlines around your images ingame, therefore avoiding blending and mipmap issues. See Edge padding for more info.

Note this works only in RGBA image files (e.g. PNG files). So, it will fail in e.g. JPEG files.

dummy_map

dummy_map

Creates a dummy, small empty map used for vanilla antispoof (sv_vanilla_antispoof). See [1] for more info.

map_convert_07

map_convert_07 src_map_file dest_map_file

Makes dest_map_file compatible with Teeworlds version 7.x that otherwise it would be compatible only with Teeworlds version 6.x. If successfully, it creates a valid 07-compatible destination map; otherwise, it returns one of the following:

  • an usage message if incorrect arguments are provided
  • failed to open source map if an error happens when opening the source map
  • failed to open destination map if an error happens when opening the destination map
  • error loading storage if failed to open storage for some reason
  • failed to open image file if error happens on opening PNG image
  • invalid image format if incorrectly formatted PNG.

Available since: DDNet 12.9

map_create_pixelart

map_create_pixelart <image.png> <img_pixelsize> <input_map> <layergroup_id> <layer_id> <pos_x> <pos_y> <quad_pixelsize> <output_map> [optimize=0|1] [centralize=0|1]

Creates a map with quad-based pixelart from an image.

Note: use destination layer tiles as a reference for positions and pixels for sizes.

Note: set img_pixelsize to 0 to consider the largest possible size.

Note: set quad_pixelsize to 0 to consider the same value of img_pixelsize.

Note: if image.png has not a perfect pixelart grid, result might be unexpected, manually fix img_pixelsize to get it better.

Options: optimize tries to reduce the total number of quads (default: 1).

Options: centralize places all pivots at the same position (default: 0).

map_diff

map_diff map_file1 map_file2

Compares two map files, reporting one of the follow:

  • no diff output, meaning the maps are the same
  • different layer numbers, if one map has more layers than another
  • different tile layers, if the number of layers is the same, but at least one layer is different
  • lastly, the index and flags positions that differ.

If there is no difference between maps, returns 0; otherwise, returns 1.

map_extract

map_extract map_file [directory]

Extracts contents from map_file into the directory. If optional argument directory is not provided, extracts to the current directory.

map_find_env

map_find_env <input_map> <env_number>

Finds quads using a specific envelope and prints their index and position to the console.

Note: returned quads positions are relative to their layers.

map_optimize

map_optimize source_map_filepath [dest_map_filepath]

Optimizes the map file in the source_map_filepath given (see how it works) and stores the output in the given dest_map_filepath; if dest_map_filepath is unset, output path defaults to out/source_map_filename.map, stripping the path and the extension of the source file.

Note the name of the embedded images optimized is changed from originalname to originalname_cut_newSHA256 (where newSHA256 is the new sha256 of the embedded optimized image). It is renamed is to make clear it was optimized because this tool will make changes in the mapres used by the map file.

If failed to open source or target file, returns -1.

Available since: DDNet 15.5.4

map_replace_area

map_replace_area <from_map> <from_x> <from_y> <to_map> <to_x> <to_y> <width> <height> <output_map>

Replaces an area of one map with an area from another map.

Note: use game layer tiles as a reference for both coordinates and sizes.

map_replace_image

map_replace_image map_file1 map_file2 imagename image_file

Replaces the image imagename currently inside the map filename map_file1 with the image filepath image_file, and save into the map filename map_file2.map.

Please note:

  • Both map filenames must be relative to user default DDNet folder
  • New image filepath can be absolute, or relative to the current directory

map_resave

map_resave source_map.map destination_map.map

Reads the map source_map.map and writes it back to destination_map.map using the latest map format.

packetgen

packetgen

Generates and sends network packets to 127.0.0.1:8303 (localhost, in default server port) to test communication with a local server instance.

stun

stun address

Sends STUN request to server and checks response.

twping

twping server[:port]

Measures ping to a teeworlds server by requesting the server information. port defaults to 8303.

unicode_confusables

unicode_confusables string1 string2

Compares string1 with string2 and report if they are "confusable", i.e. if the characters are "equal" and could cause confusion. For this to work, the characters with accents or other things around them are considered the "confusable" with the base character. Therefore, aa and aá are confusable (á was considered as a), while aa and ab are not.

If they are confusable, it returns not_confusable=0, otherwise, returns not_confusable=1.

Available since: DDNet 10.3.5

New in DDNet 12.9: Unicode 12.0 support and the tool name was renamed from confusables to unicode_confusables.

uuid

uuid name

Prints uuid for the provided name.

The uuid system was implemented to be easily extended by independent authors without collisions, something that the old system – with increasing integers – did not allow. This works for engine and game messages, snapshot items and events.

Exits with error status 255 if name is not provided.

Available since: DDNet 10.6.1

Retrieved from "https://wiki.ddnet.org/index.php?title=Extra_tools&oldid=31607"