Multi Theft Auto: Wiki - User contributions [en]

RU/Writing Gamemodes

2011-05-30T05:58:28Z

103495106181459904329: /* Менеджер карт */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указания к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Файлы карт===
Файлы карт основываются на XML документах с форматом .map. Они определяют контекст игры для одного или нескольких конкретных игровых режимов. Однако, они не должны менять правила игры, которые определены игровым режимом.

Каждый элемент на карте соответствует узлу .map файла. Существует стандартный синтаксис для общих элементов, таких как точки появления игроков, объекты и транспортные средства. Для особых же элементов карты, соответствующих специфике игрового режима, вам нужно придумать собственный синтаксис.

====Пример====
Давайте для примера возьмем режим Capture the Flag. Карта для этого режима нуждается главным образом в определенных точках появления игроков, расположенных флагах и в конце концов объектах и транспортных средствах. Упрощенный файл карты может выглядеть следующим образом:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Здесь вы можете увидеть два MTA элемента - точку появления игрока и пикап. Что еще более важно, карта имеет пользовательский узел "flag", который определяет положение и цвет флага. Точка появления игрока и пикап могут быть обработаны путем существующих внешних ресурсов, пользовательские элементы должны быть обработаны игровым режимом.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Пример получения .map информации====
Как уже упоминалось выше, вашему игровому режиму нужно получить пользовательские элементы, которые определены в файле карты, и обработать их. Это довольно просто, как показано ниже.
<syntaxhighlight lang="lua">
-- получаем таблицу со всеми элементами типа "flag"
local flagElements = getElementsByType ( "flag" )
-- пропускаем их через цикл
for key, value in pairs(flagElements) do
-- получаем нашу информацию
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- создаем объект в соответствии с положением флага
createObject ( 1337, posX, posY, posZ )
-- выводим команду, для которой мы создали базу
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
Функция [[getElementsByType]] возвращает таблицу всех элементов определенного типа (тип соответствует имени узла в .map файле). Это работает как с пользовательскими типами, так и со встроенными в МТА(например, "vehicle" или "player").
[[getElementData]] может быть использована для получения XML-атрибутов в .map файле.
В этом простом примере объект создается на месте флага и в окно чата выводится сообщение. В действительности, вы конечно должны делать все это во время загрузки карты, так как в этом случае создается форма столкновения для обнаружения игроков с флагом.

==Менеджер карт==
Прочитав раздел выше должно быть понятно, что игровой режим всегда должен состоять из двух частей:
* Ресурс игрового режима, который всегда остается неизменным
* Множество различных ресурсов карт, которые дают игровому режиму конкретную карту содержащую информацию

Теперь, вместо того чтобы писать загрузчик карт для каждого игрового режима, [[Map manager]] предоставляет функции для загрузки этих самых режимов и карт. Проще говоря, когда вы вводите правильную команду (например 'gamemode ctf ctf-italy'), запускаются ресурсы 'ctf' и 'ctf-italy' вызывая событие ([[onGamemodeMapStart]]) говорящее что для ресурса 'ctf' была загружена карта. Ресурс 'ctf' может получить доступ к информации 'ctf-italy' содержащую стартовые точки для игроков.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T05:47:58Z

103495106181459904329: /* Менеджер карт */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указания к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Файлы карт===
Файлы карт основываются на XML документах с форматом .map. Они определяют контекст игры для одного или нескольких конкретных игровых режимов. Однако, они не должны менять правила игры, которые определены игровым режимом.

Каждый элемент на карте соответствует узлу .map файла. Существует стандартный синтаксис для общих элементов, таких как точки появления игроков, объекты и транспортные средства. Для особых же элементов карты, соответствующих специфике игрового режима, вам нужно придумать собственный синтаксис.

====Пример====
Давайте для примера возьмем режим Capture the Flag. Карта для этого режима нуждается главным образом в определенных точках появления игроков, расположенных флагах и в конце концов объектах и транспортных средствах. Упрощенный файл карты может выглядеть следующим образом:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Здесь вы можете увидеть два MTA элемента - точку появления игрока и пикап. Что еще более важно, карта имеет пользовательский узел "flag", который определяет положение и цвет флага. Точка появления игрока и пикап могут быть обработаны путем существующих внешних ресурсов, пользовательские элементы должны быть обработаны игровым режимом.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Пример получения .map информации====
Как уже упоминалось выше, вашему игровому режиму нужно получить пользовательские элементы, которые определены в файле карты, и обработать их. Это довольно просто, как показано ниже.
<syntaxhighlight lang="lua">
-- получаем таблицу со всеми элементами типа "flag"
local flagElements = getElementsByType ( "flag" )
-- пропускаем их через цикл
for key, value in pairs(flagElements) do
-- получаем нашу информацию
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- создаем объект в соответствии с положением флага
createObject ( 1337, posX, posY, posZ )
-- выводим команду, для которой мы создали базу
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
Функция [[getElementsByType]] возвращает таблицу всех элементов определенного типа (тип соответствует имени узла в .map файле). Это работает как с пользовательскими типами, так и со встроенными в МТА(например, "vehicle" или "player").
[[getElementData]] может быть использована для получения XML-атрибутов в .map файле.
В этом простом примере объект создается на месте флага и в окно чата выводится сообщение. В действительности, вы конечно должны делать все это во время загрузки карты, так как в этом случае создается форма столкновения для обнаружения игроков с флагом.

==Менеджер карт==
Прочитав раздел выше должно быть понятно, что игровой режим всегда должен состоять из двух частей:
* Ресурс игрового режима, который всегда остается неизменным
* Множество различных ресурсов карт, которые дают игровому режиму конкретную карту содержащую информацию

Теперь вместо того чтобы писать загрузчик карт для каждого игрового режима, [[Map manager]] предоставляет функции для загрузки этих самых режимов и карт. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T05:47:34Z

103495106181459904329: /* Map manager */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указания к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Файлы карт===
Файлы карт основываются на XML документах с форматом .map. Они определяют контекст игры для одного или нескольких конкретных игровых режимов. Однако, они не должны менять правила игры, которые определены игровым режимом.

Каждый элемент на карте соответствует узлу .map файла. Существует стандартный синтаксис для общих элементов, таких как точки появления игроков, объекты и транспортные средства. Для особых же элементов карты, соответствующих специфике игрового режима, вам нужно придумать собственный синтаксис.

====Пример====
Давайте для примера возьмем режим Capture the Flag. Карта для этого режима нуждается главным образом в определенных точках появления игроков, расположенных флагах и в конце концов объектах и транспортных средствах. Упрощенный файл карты может выглядеть следующим образом:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Здесь вы можете увидеть два MTA элемента - точку появления игрока и пикап. Что еще более важно, карта имеет пользовательский узел "flag", который определяет положение и цвет флага. Точка появления игрока и пикап могут быть обработаны путем существующих внешних ресурсов, пользовательские элементы должны быть обработаны игровым режимом.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Пример получения .map информации====
Как уже упоминалось выше, вашему игровому режиму нужно получить пользовательские элементы, которые определены в файле карты, и обработать их. Это довольно просто, как показано ниже.
<syntaxhighlight lang="lua">
-- получаем таблицу со всеми элементами типа "flag"
local flagElements = getElementsByType ( "flag" )
-- пропускаем их через цикл
for key, value in pairs(flagElements) do
-- получаем нашу информацию
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- создаем объект в соответствии с положением флага
createObject ( 1337, posX, posY, posZ )
-- выводим команду, для которой мы создали базу
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
Функция [[getElementsByType]] возвращает таблицу всех элементов определенного типа (тип соответствует имени узла в .map файле). Это работает как с пользовательскими типами, так и со встроенными в МТА(например, "vehicle" или "player").
[[getElementData]] может быть использована для получения XML-атрибутов в .map файле.
В этом простом примере объект создается на месте флага и в окно чата выводится сообщение. В действительности, вы конечно должны делать все это во время загрузки карты, так как в этом случае создается форма столкновения для обнаружения игроков с флагом.

==Менеджер карт==
Прочитав раздел выше должно быть понятно, что режим игры всегда должен состоять из двух частей:
* Ресурс игрового режима, который всегда остается неизменным
* Множество различных ресурсов карт, которые дают игровому режиму конкретную карту содержащую информацию

Теперь вместо того чтобы писать загрузчик карт для каждого игрового режима, [[Map manager]] предоставляет функции для загрузки этих самых режимов и карт. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T05:41:06Z

103495106181459904329: /* Пример получения .map информации */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указания к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Файлы карт===
Файлы карт основываются на XML документах с форматом .map. Они определяют контекст игры для одного или нескольких конкретных игровых режимов. Однако, они не должны менять правила игры, которые определены игровым режимом.

Каждый элемент на карте соответствует узлу .map файла. Существует стандартный синтаксис для общих элементов, таких как точки появления игроков, объекты и транспортные средства. Для особых же элементов карты, соответствующих специфике игрового режима, вам нужно придумать собственный синтаксис.

====Пример====
Давайте для примера возьмем режим Capture the Flag. Карта для этого режима нуждается главным образом в определенных точках появления игроков, расположенных флагах и в конце концов объектах и транспортных средствах. Упрощенный файл карты может выглядеть следующим образом:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Здесь вы можете увидеть два MTA элемента - точку появления игрока и пикап. Что еще более важно, карта имеет пользовательский узел "flag", который определяет положение и цвет флага. Точка появления игрока и пикап могут быть обработаны путем существующих внешних ресурсов, пользовательские элементы должны быть обработаны игровым режимом.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Пример получения .map информации====
Как уже упоминалось выше, вашему игровому режиму нужно получить пользовательские элементы, которые определены в файле карты, и обработать их. Это довольно просто, как показано ниже.
<syntaxhighlight lang="lua">
-- получаем таблицу со всеми элементами типа "flag"
local flagElements = getElementsByType ( "flag" )
-- пропускаем их через цикл
for key, value in pairs(flagElements) do
-- получаем нашу информацию
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- создаем объект в соответствии с положением флага
createObject ( 1337, posX, posY, posZ )
-- выводим команду, для которой мы создали базу
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
Функция [[getElementsByType]] возвращает таблицу всех элементов определенного типа (тип соответствует имени узла в .map файле). Это работает как с пользовательскими типами, так и со встроенными в МТА(например, "vehicle" или "player").
[[getElementData]] может быть использована для получения XML-атрибутов в .map файле.
В этом простом примере объект создается на месте флага и в окно чата выводится сообщение. В действительности, вы конечно должны делать все это во время загрузки карты, так как в этом случае создается форма столкновения для обнаружения игроков с флагом.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T05:34:36Z

103495106181459904329: /* Пример получения .map информации */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указания к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Файлы карт===
Файлы карт основываются на XML документах с форматом .map. Они определяют контекст игры для одного или нескольких конкретных игровых режимов. Однако, они не должны менять правила игры, которые определены игровым режимом.

Каждый элемент на карте соответствует узлу .map файла. Существует стандартный синтаксис для общих элементов, таких как точки появления игроков, объекты и транспортные средства. Для особых же элементов карты, соответствующих специфике игрового режима, вам нужно придумать собственный синтаксис.

====Пример====
Давайте для примера возьмем режим Capture the Flag. Карта для этого режима нуждается главным образом в определенных точках появления игроков, расположенных флагах и в конце концов объектах и транспортных средствах. Упрощенный файл карты может выглядеть следующим образом:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Здесь вы можете увидеть два MTA элемента - точку появления игрока и пикап. Что еще более важно, карта имеет пользовательский узел "flag", который определяет положение и цвет флага. Точка появления игрока и пикап могут быть обработаны путем существующих внешних ресурсов, пользовательские элементы должны быть обработаны игровым режимом.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Пример получения .map информации====
Как уже упоминалось выше, вашему игровому режиму нужно получить пользовательские элементы, которые определены в файле карты, и обработать их. Это довольно просто, как показано ниже.
<syntaxhighlight lang="lua">
-- получаем таблицу со всеми элементами типа "flag"
local flagElements = getElementsByType ( "flag" )
-- пропускаем их через цикл
for key, value in pairs(flagElements) do
-- получаем нашу информацию
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- создаем объект в соответствии с положением флага
createObject ( 1337, posX, posY, posZ )
-- выводим команду, для которой мы создали базу
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
Функция [[getElementsByType]] возвращает таблицу всех элементов определенного типа (тип соответствует имени узла в .map файле). Это работает как с пользовательскими типами, так и с встроенными в МТА(например, "vehicle" или "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T05:29:37Z

103495106181459904329: /* Example of getting the .map information */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указания к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Файлы карт===
Файлы карт основываются на XML документах с форматом .map. Они определяют контекст игры для одного или нескольких конкретных игровых режимов. Однако, они не должны менять правила игры, которые определены игровым режимом.

Каждый элемент на карте соответствует узлу .map файла. Существует стандартный синтаксис для общих элементов, таких как точки появления игроков, объекты и транспортные средства. Для особых же элементов карты, соответствующих специфике игрового режима, вам нужно придумать собственный синтаксис.

====Пример====
Давайте для примера возьмем режим Capture the Flag. Карта для этого режима нуждается главным образом в определенных точках появления игроков, расположенных флагах и в конце концов объектах и транспортных средствах. Упрощенный файл карты может выглядеть следующим образом:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Здесь вы можете увидеть два MTA элемента - точку появления игрока и пикап. Что еще более важно, карта имеет пользовательский узел "flag", который определяет положение и цвет флага. Точка появления игрока и пикап могут быть обработаны путем существующих внешних ресурсов, пользовательские элементы должны быть обработаны игровым режимом.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Пример получения .map информации====
Как уже упоминалось выше, вашему игровому режиму нужно получить пользовательские элементы, которые определены в файле карты, и обработать их. Это довольно просто, как показано ниже.
<syntaxhighlight lang="lua">
-- получаем таблицу со всеми элементами типа "flag"
local flagElements = getElementsByType ( "flag" )
-- пропускаем их через цикл
for key, value in pairs(flagElements) do
-- получаем нашу информацию
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- создаем объект в соответствии с положением флага
createObject ( 1337, posX, posY, posZ )
-- выводим команду, для которой мы создали базу
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T05:22:07Z

103495106181459904329: /* Пример */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указания к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Файлы карт===
Файлы карт основываются на XML документах с форматом .map. Они определяют контекст игры для одного или нескольких конкретных игровых режимов. Однако, они не должны менять правила игры, которые определены игровым режимом.

Каждый элемент на карте соответствует узлу .map файла. Существует стандартный синтаксис для общих элементов, таких как точки появления игроков, объекты и транспортные средства. Для особых же элементов карты, соответствующих специфике игрового режима, вам нужно придумать собственный синтаксис.

====Пример====
Давайте для примера возьмем режим Capture the Flag. Карта для этого режима нуждается главным образом в определенных точках появления игроков, расположенных флагах и в конце концов объектах и транспортных средствах. Упрощенный файл карты может выглядеть следующим образом:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Здесь вы можете увидеть два MTA элемента - точку появления игрока и пикап. Что еще более важно, карта имеет пользовательский узел "flag", который определяет положение и цвет флага. Точка появления игрока и пикап могут быть обработаны путем существующих внешних ресурсов, пользовательские элементы должны быть обработаны игровым режимом.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T05:09:04Z

103495106181459904329: /* Файлы карт */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указания к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Файлы карт===
Файлы карт основываются на XML документах с форматом .map. Они определяют контекст игры для одного или нескольких конкретных игровых режимов. Однако, они не должны менять правила игры, которые определены игровым режимом.

Каждый элемент на карте соответствует узлу .map файла. Существует стандартный синтаксис для общих элементов, таких как точки появления игроков, объекты и транспортные средства. Для особых же элементов карты, соответствующих специфике игрового режима, вам нужно придумать собственный синтаксис.

====Пример====
Давайте для примера возьмем режим Capture the Flag. Карта для этого режима нуждается главным образом в определенных точках появления игроков, расположенных флагах и в конце концов объектах и транспортных средствах. Упрощенный файл карты может выглядеть следующим образом:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Here you can see two MTA elements - a spawnpoint and a pickup. More importantly, this .map has a custom "flag" node which defines the position and color of the flag. The spawnpoint and pickup can be handled by existing external resources, custom elements have to be processed by the gamemode.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T04:57:15Z

103495106181459904329: /* Map Files */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указания к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Файлы карт===
Файлы карт основываются на XML документах с форматом .map. Они определяют контекст игры для одного или нескольких конкретных игровых режимов. Однако, они не должны менять правила игры, которые определены игровым режимом.

Каждый элемент на карте соответствует узлу .map файла. There is standard syntax for common things like spawnpoints, objects and vehicles; however, for "special", gamemode specific information, you need to invent your own syntax.

====Example====
Let's take a Capture the Flag gamemode as an example. A map for this gamemode needs to mainly define spawnpoints and flag locations, and eventually objects and vehicles. A simplified map file could look like this:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Here you can see two MTA elements - a spawnpoint and a pickup. More importantly, this .map has a custom "flag" node which defines the position and color of the flag. The spawnpoint and pickup can be handled by existing external resources, custom elements have to be processed by the gamemode.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T04:45:18Z

103495106181459904329: /* Введение */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указания к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Map Files===
Map files are basically XML documents with a .map extension. They define an environment to play one or more specific gamemodes in. They are however not supposed to change the rules of the game - those are defined by the gamemode.

Each element in a map corresponds to a node in the .map file. There is standard syntax for common things like spawnpoints, objects and vehicles; however, for "special", gamemode specific information, you need to invent your own syntax.

====Example====
Let's take a Capture the Flag gamemode as an example. A map for this gamemode needs to mainly define spawnpoints and flag locations, and eventually objects and vehicles. A simplified map file could look like this:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Here you can see two MTA elements - a spawnpoint and a pickup. More importantly, this .map has a custom "flag" node which defines the position and color of the flag. The spawnpoint and pickup can be handled by existing external resources, custom elements have to be processed by the gamemode.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T04:44:40Z

103495106181459904329: /* Введение */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод, игровой режим) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указаний к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Map Files===
Map files are basically XML documents with a .map extension. They define an environment to play one or more specific gamemodes in. They are however not supposed to change the rules of the game - those are defined by the gamemode.

Each element in a map corresponds to a node in the .map file. There is standard syntax for common things like spawnpoints, objects and vehicles; however, for "special", gamemode specific information, you need to invent your own syntax.

====Example====
Let's take a Capture the Flag gamemode as an example. A map for this gamemode needs to mainly define spawnpoints and flag locations, and eventually objects and vehicles. A simplified map file could look like this:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Here you can see two MTA elements - a spawnpoint and a pickup. More importantly, this .map has a custom "flag" node which defines the position and color of the flag. The spawnpoint and pickup can be handled by existing external resources, custom elements have to be processed by the gamemode.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T04:44:20Z

103495106181459904329: /* Введение */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя отправку сообщений игрокам - указаний к действиям, респаун игроков, создание команд, указаний, что игрокам нужно делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и.

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Map Files===
Map files are basically XML documents with a .map extension. They define an environment to play one or more specific gamemodes in. They are however not supposed to change the rules of the game - those are defined by the gamemode.

Each element in a map corresponds to a node in the .map file. There is standard syntax for common things like spawnpoints, objects and vehicles; however, for "special", gamemode specific information, you need to invent your own syntax.

====Example====
Let's take a Capture the Flag gamemode as an example. A map for this gamemode needs to mainly define spawnpoints and flag locations, and eventually objects and vehicles. A simplified map file could look like this:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Here you can see two MTA elements - a spawnpoint and a pickup. More importantly, this .map has a custom "flag" node which defines the position and color of the flag. The spawnpoint and pickup can be handled by existing external resources, custom elements have to be processed by the gamemode.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T04:41:52Z

103495106181459904329: /* Что означает "правильный игровой режим"? */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя посылку сообщений игрокам - указания к действиям; респауном игроков; созданием команд; указанием, что игрокам надо делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

Очевидным примеров "правильного игрового режима" является MTA: Race. Он допускает пользовательские карты с большим количеством возможностей внутри .map файла. Чтобы изменить точки появления игроков, объекты и т.д., пользователю не нужно изменять сам игровой режим.

===Map Files===
Map files are basically XML documents with a .map extension. They define an environment to play one or more specific gamemodes in. They are however not supposed to change the rules of the game - those are defined by the gamemode.

Each element in a map corresponds to a node in the .map file. There is standard syntax for common things like spawnpoints, objects and vehicles; however, for "special", gamemode specific information, you need to invent your own syntax.

====Example====
Let's take a Capture the Flag gamemode as an example. A map for this gamemode needs to mainly define spawnpoints and flag locations, and eventually objects and vehicles. A simplified map file could look like this:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Here you can see two MTA elements - a spawnpoint and a pickup. More importantly, this .map has a custom "flag" node which defines the position and color of the flag. The spawnpoint and pickup can be handled by existing external resources, custom elements have to be processed by the gamemode.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T04:35:30Z

103495106181459904329: /* Что означает "правильный игровой режим"? */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя посылку сообщений игрокам - указания к действиям; респауном игроков; созданием команд; указанием, что игрокам надо делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, такие как положение игроков или автомобилей. Вместо этого, игровой режим должен быть в состоянии загружать .map файлы, которые и будут определять эти данные. Таким образом, игровой режим может иметь несколько карт, а также люди смогут создавать .map файлы для игрового режима используя MTA редактор карт, который является гораздо более удобным, чем написание кода.

An obvious example of a "proper gamemode" is MTA:Race. It allows usermade maps with lots of possibilities within the .map file. To alter spawnpoints, objects etc., the user doesn't need to edit the gamemode itself.

===Map Files===
Map files are basically XML documents with a .map extension. They define an environment to play one or more specific gamemodes in. They are however not supposed to change the rules of the game - those are defined by the gamemode.

Each element in a map corresponds to a node in the .map file. There is standard syntax for common things like spawnpoints, objects and vehicles; however, for "special", gamemode specific information, you need to invent your own syntax.

====Example====
Let's take a Capture the Flag gamemode as an example. A map for this gamemode needs to mainly define spawnpoints and flag locations, and eventually objects and vehicles. A simplified map file could look like this:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Here you can see two MTA elements - a spawnpoint and a pickup. More importantly, this .map has a custom "flag" node which defines the position and color of the flag. The spawnpoint and pickup can be handled by existing external resources, custom elements have to be processed by the gamemode.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]

RU/Writing Gamemodes

2011-05-30T04:25:16Z

103495106181459904329: /* What does "proper gamemode" mean? */

{{translate}}
Это руководство поможет вам, как написать правильный режим игры. Если вы только что начали писать скрипты для MTA, вы должны сначала просмотреть другие учебники на [[RU/Main Page|Главная страница]].
==Введение==
Gamemode (ГМ, мод, гейммод) - ресурс, который, будучи запущенным, контролирует весь игровой процесс. Гейммод включает в себя посылку сообщений игрокам - указания к действиям; респауном игроков; созданием команд; указанием, что игрокам надо делать для победы, или для получения очков, и т.д. Примеры - гонки и DeatMatch'и

==Что означает "правильный игровой режим"?==
Проще говоря, правильным игровым режимом можно назвать такой режим, который в полной мере использует MTA систему .map файлов. Это означает, что код игрового режима не имеет любых специфических карт, данные которых жестко привязаны к нему, таких как положение игроков или автомобилей. Instead, the gamemode should be able to load .map files which define these data. This way the gamemode can have multiple maps; also, people can create .map files for the gamemode with MTA's map editor, which is much more convenient than writing code.

An obvious example of a "proper gamemode" is MTA:Race. It allows usermade maps with lots of possibilities within the .map file. To alter spawnpoints, objects etc., the user doesn't need to edit the gamemode itself.

===Map Files===
Map files are basically XML documents with a .map extension. They define an environment to play one or more specific gamemodes in. They are however not supposed to change the rules of the game - those are defined by the gamemode.

Each element in a map corresponds to a node in the .map file. There is standard syntax for common things like spawnpoints, objects and vehicles; however, for "special", gamemode specific information, you need to invent your own syntax.

====Example====
Let's take a Capture the Flag gamemode as an example. A map for this gamemode needs to mainly define spawnpoints and flag locations, and eventually objects and vehicles. A simplified map file could look like this:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Here you can see two MTA elements - a spawnpoint and a pickup. More importantly, this .map has a custom "flag" node which defines the position and color of the flag. The spawnpoint and pickup can be handled by existing external resources, custom elements have to be processed by the gamemode.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.

end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[en:Writing Gamemodes]]
[[it:Scrivere una gamemode]]