https://wiki.multitheftauto.com/api.php?action=feedcontributions&feedformat=atom&user=JoeZhaoMulti Theft Auto: Wiki - User contributions [en]2026-04-08T19:38:31ZUser contributionsMediaWiki 1.39.3https://wiki.multitheftauto.com/index.php?title=ZH-CN/Resource:Editor&diff=37547ZH-CN/Resource:Editor2013-11-11T15:06:22Z<p>JoeZhao: Created page with "{{Resource page}} MTA:SA 地图编辑器允许您创建游戏模式的地图。 ==开始创建== 单击 MTA 主菜单上的 "Map editor" 选项以启动地图编辑器。 ==菜..."</p>
<hr />
<div>{{Resource page}}<br />
MTA:SA 地图编辑器允许您创建游戏模式的地图。<br />
<br />
==开始创建==<br />
单击 MTA 主菜单上的 "Map editor" 选项以启动地图编辑器。<br />
<br />
==菜单==<br />
地图编辑器启动后，可以看到有两条菜单栏：位于顶部的主菜单，以及位于左下方的元素菜单。<br />
<br />
===主菜单===<br />
主菜单中有以下的选项：<br />
* [[Image:Editor_New.png]] 创建新地图。<br />
* [[Image:Editor_Open.png]] 打开已有地图。<br />
* [[Image:Editor_Save.png]] 保存地图编辑进度。<br />
* [[Image:Editor_Save_as.png]] 另存地图。<br />
* [[Image:Editor_Options.png]] 修改地图编辑器通用设置。<br />
* [[Image:Editor_Undo.png]] 撤销上一次的更改。<br />
* [[Image:Editor_Redo.png]] 还原上一次的更改。<br />
* [[Image:Editor_Locations.png]] 储存游戏世界的各个重要坐标。地图编辑器内有列举了 San Andreas 所有室内空间坐标的列表，但您也可以自行向该列表内添加室内及非室内坐标。<br />
* [[Image:Editor_Current_elements.png]] 列举该地图内所包含的所有元素（对象、交通工具、标识等）。<br />
* [[Image:Editor_Map_settings.png]] 地图设置，例如事件、重力等。也可以设置该地图所支持的游戏模式。<br />
* [[Image:Editor_Definitions.png]] 加载您想要使用的[[Resource:Editor/EDF|地图编辑器定义文件 (EDF)]]。<br />
* [[Image:Editor_Test.png]] 测试地图。同时加载该地图所支持的游戏模式以进行游戏测试。<br />
<br />
===元素菜单===<br />
元素菜单用于向地图中添加新元素。<br />
* [[Image:Editor_Vehicle.png]] 创建新交通工具。<br />
* [[Image:Editor_Object.png]] 创建新对象（建筑物、道路、装饰物等）。<br />
* [[Image:Editor_Pickup.png]] 创建新拾取物（补血、补防护、武器及自定义拾取物）。<br />
* [[Image:Editor_Marker.png]] 创建新标识（检查点、圆环、圆柱、箭头及光影）。<br />
* [[File:Crosshair.png]] 选择世界对象。<br />
此外，如果您加载了[[Resource:Editor/EDF|地图编辑器定义]]，您可以在元素菜单上滚动鼠标滚轮以浏览自定义元素。<br />
<br />
==使用地图编辑器==<br />
本节介绍如何创建及修改地图。<br />
<br />
===移动地图===<br />
When you initially start the editor, you are in ''camera mode''. You are able to use the '''WSAD''' keys to move the camera and the mouse to pan the camera. While moving around, you can hold '''ALT''' to move more slowly or '''SHIFT''' to go faster.<br />
当初次启动地图编辑器，当前模式为 ''摄影机模式''。您可以使用 '''WSAD''' 键<br />
<br />
To access the editor's interface and control panel you need to switch to ''cursor mode''. You can toggle between cursor mode and camera mode with the '''F''' key. When in cursor mode, your view is fixed, and you can use the mouse cursor to manipulate elements and use the graphical interface.<br />
<br />
Camera mode can be recognized by a crosshair in the center of the screen. You can use it to select and move elements just like in cursor mode.<br />
<br />
[[Image:Editor_Crosshair.png|center]]<br />
<br />
===Starting a new map===<br />
* Start the editor, or if it is already started, click the ''New'' menu button.<br />
* Click the ''Map settings'' button. In the ''Meta'' tab, fill in the Name and Author fields with the name of the map and your name respectively. Also open the ''Gamemodes'' tab and add the gamemodes your map is meant for (they will be moved to the ''Added gamemodes'' list). You can do this by selecting them and clicking ''Add'', or by double clicking them. Click OK when you're done.<br />
[[Image:Editor_Mapsettings.png|center]]<br />
* Click the ''Definitions'' window and add the resources of which you want to use the custom elements. These will consist of the gamemodes you selected in the ''Map settings'' window, plus eventual additional resources. For more information about editor definitions, see [[Resource:Editor/EDF|EDF]]. Click OK when you're done.<br />
<br />
===Creating new elements===<br />
Adding elements to your map, such as vehicles and objects, is very straightforward.<br />
* If you are in camera mode, switch to cursor mode first by pressing '''F'''.<br />
* Click the button in the element menu that represents what you want. E.g., click the button with a car on it to add a vehicle.<br />
* A new element of the selected type will be created and attached to your cursor. Move it to the location where you want it and '''left click''' to drop it off.<br />
<br />
<br />
[[Image:Editor_Addelem.png|center]]<br />
<br />
<br />
To create custom elements that are specific to a resource, hover the cursor over the element menu and turn the scroll wheel until the desired resource comes up. Note that for this to work, you first have to add the [[Resource:Editor/EDF|EDF]] file of the resource in the ''Definitions'' window.<br />
<br />
[[Image:Editor_Selectedf.png|center]]<br />
<br />
===Selecting===<br />
* '''Left click''' an element to select it in ''keyboard mode''.<br />
* '''Right click''' it to select it in ''mouse mode''.<br />
* Press the '''Spacebar''' or click in an empty area to deselect.<br />
<br />
The selected element, if any, is denoted by a yellow cone marker. Elements (particularly objects) with poor collisions can be detected easier by enabling ''High sensitivity mode'', by pressing the '''E''' key. This increases detection at the expense of accuracy.<br />
<br />
The ''Current elements'' dialog can also be used to select elements. Double-clicking an item within the list will select it in ''Keyboard mode''.<br />
<br />
===Moving===<br />
Moving elements can be done in several ways.<br />
<br />
'''With the mouse'''<br />
* Simply drag and drop with the '''left mouse button'''.<br />
Or:<br />
* Select the element in mouse mode ('''right click'''), move it to where you want it, and click to drop it off.<br />
<br />
You can also adjust the ''Hold distance'' of an element toward and away from the camera by switching to camera mode, '''right clicking''' the element, and rolling the '''mouse wheel'''.<br />
<br />
'''With the keyboard'''<br />
* Select the element in keyboard mode ('''left click''').<br />
* Use the '''arrow keys''' to move the element in the horizontal plane, and '''PgUp'''/'''PgDn''' to move it vertically. Hold '''ALT''' to decrease the movement speed, or '''SHIFT''' to increase it.<br />
<br />
By default, elements move relative to the camera and are not locked to any axes. This can be disabled in the ''Options'' menu.<br />
<br />
===Rotating===<br />
'''With the mouse'''<br />
<br />
You can rotate selected elements around the Z axis with the mouse wheel.<br />
* Select the element in keyboard mode ('''left click''') and roll the mouse wheel while holding '''Left CTRL'''.<br />
Or:<br />
* Select the element in mouse mode ('''right click'''), hold '''CTRL''', and roll the mouse wheel.<br />
<br />
'''With the keyboard'''<br />
* Select the element in keyboard mode ('''left click''').<br />
* While holding '''CTRL''' (the selection marker will turn green), use the '''arrow keys''' and '''PgUp'''/'''PgDn''' to rotate the element around the different axes.<br />
<br />
With both methods you can additionally hold '''ALT''' to decrease the rotation speed or '''SHIFT''' to increase it.<br />
<br />
<br />
[[Image:Editor_Rotateelem.png|center]]<br />
<br />
===Changing model and other properties===<br />
Most elements have a variety of options that can be altered to change their appearance and behaviour. Examples are the model, color and visual upgrades of a car.<br />
<br />
* Open the properties window of an element by either double clicking it or by selecting it and pressing '''F3'''.<br />
* Make any alterations that you want. For example, to change the model of a car or object, click the '''Browse''' button next to "model" to open the model browser.<br />
* Click OK when you're done.<br />
<br />
[[Image:Editor_Props.png|center]]<br />
<br />
===Cloning===<br />
You can clone an element by selecting it and pressing '''C'''. <br />
<br />
* In mouse mode the cloned element will be attached to your cursor. '''Left click''' to place it in the map.<br />
* In keyboard mode the cloned element will be cloned in the identical position.<br />
<br />
If you hold '''CTRL''' while clicking, the element will be cloned again and will again be attached to the cursor. This way you can easily place large quantities of something.<br />
<br />
Alternatively you can use the ''Pullout'' button located in the bottom-right corner of the properties box to clone an element.<br />
<br />
===Deleting===<br />
Simply select the element and press '''DEL''' ''(Delete)''.<br />
<br />
Alternatively you can use the ''Pullout'' button located in the bottom-right corner of the properties box to delete an element.<br />
<br />
==Creating maps for specific gamemodes==<br />
To make a map for a specific gamemode, you have to do two things:<br />
* Click the '''Map Settings''' button in the top menu, go to the '''Gamemodes''' tab and add any gamemodes that your map is to be used with.<br />
* You will likely also need to add one or more [[Resource:Editor/EDF|Editor Definition Files]]. These will allow you to place gamemode specific elements in the map, like spawnpoints, race checkpoints, or CTF flags. You can add EDF's by clicking the '''Definitions''' menu button and adding the relevant gamemodes.<br />
<br />
==Controls==<br />
Here is a list of all default controls. To change them please go to the MTA Settings menu while the Editor is started.<br />
<br />
===Camera===<br />
{|<br />
|-<br />
| camera_move_forwards<br />
| '''w'''<br />
|-<br />
| camera_move_backwards<br />
| '''s'''<br />
|-<br />
| camera_move_left<br />
| '''a'''<br />
|-<br />
| camera_move_right<br />
| '''d'''<br />
|-<br />
| high_sensitivity_mode<br />
| '''e'''<br />
|}<br />
<br />
===Cloning===<br />
{|<br />
|-<br />
| clone_selected_element<br />
| '''c'''<br />
|-<br />
| clone_drop_modifier<br />
| '''lctrl''' || ''(Left CTRL)''<br />
|}<br />
<br />
===Element manipulation===<br />
{|<br />
|-<br />
| element_move_forward<br />
| '''arrow_u''' || ''(Arrow key Up)''<br />
|-<br />
| element_move_backward<br />
| '''arrow_d''' || ''(Arrow key Down)''<br />
|-<br />
| element_move_left<br />
| '''arrow_l''' || ''(Arrow key Left)''<br />
|-<br />
| element_move_right<br />
| '''arrow_r''' || ''(Arrow key Right)''<br />
|-<br />
| element_move_downwards<br />
| '''pgdn''' || ''(Page Down)''<br />
|-<br />
| element_move_upwards<br />
| '''pgup''' || ''(Page Up)''<br />
|-<br />
| zoom_in<br />
| '''mouse_wheel_down'''<br />
|-<br />
| zoom_out<br />
| '''mouse_wheel_up'''<br />
|-<br />
| quick_rotate_increase<br />
| '''mod_rotate''' + '''mouse_wheel_up''' || ''(Left CTRL + Mouse wheel Up)''<br />
|-<br />
| quick_rotate_decrease<br />
| '''mod_rotate''' + '''mouse_wheel_down''' || ''(Left CTRL + Mouse wheel Down)''<br />
|-<br />
| mod_rotate<br />
| '''lctrl''' || ''(Left CTRL)''<br />
|-<br />
| mod_slow_speed<br />
| '''lalt''' || ''(Left ALT)''<br />
|-<br />
| mod_fast_speed<br />
| '''lshift''' || ''(Left SHIFT)''<br />
|-<br />
| destroy_selected_element<br />
| '''delete'''<br />
|-<br />
| drop_selected_element<br />
| '''space'''<br />
|-<br />
| pickup_selected_element<br />
| '''F2'''<br />
|-<br />
| reset_rotation<br />
| '''mod_rotate''' + '''r''' || ''(Left CTRL + R)''<br />
|}<br />
<br />
===GUI===<br />
{|<br />
| toggle_gui_display<br />
| '''F4'''<br />
|-<br />
| toggle_cursor<br />
| '''f'''<br />
|-<br />
| select_target_keyboard<br />
| '''mouse1''' || ''(Left Mouse button)''<br />
|-<br />
| select_target_mouse<br />
| '''mouse2''' || ''(Right Mouse button)''<br />
|-<br />
| edf_next<br />
| '''mouse_wheel_up'''<br />
|-<br />
| edf_prev<br />
| '''mouse_wheel_down'''<br />
|-<br />
| undo<br />
| '''Ctrl''' + '''z'''<br />
|-<br />
| redo<br />
| '''Ctrl''' + '''y'''<br />
|-<br />
| properties_toggle<br />
| '''F3'''<br />
|-<br />
| browser_up<br />
| '''arrow_u''' || ''(Arrow key Up)''<br />
|-<br />
| browser_down<br />
| '''arrow_d''' || ''(Arrow key Down)''<br />
|-<br />
| browser_zoom_in<br />
| '''mouse_wheel_up'''<br />
|-<br />
| browser_zoom_out<br />
| '''mouse_wheel_down'''<br />
|-<br />
| browser_confirm<br />
| '''enter'''<br />
|-<br />
| currentelements_up<br />
| '''num_8''' || ''(Numpad key 8)''<br />
|-<br />
| currentelements_down<br />
| '''num_2''' || ''(Numpad key 2)''<br />
|-<br />
| toggle_test<br />
| '''F5'''<br />
|}<br />
<br />
==Multiplayer==<br />
The editor is built with both serverside and clientside components, and therefore supports multiplayer out of the box. To use the editor in multiplayer with other players, simply copy all of the editor's resources into your server, start the '''editor''' resource and allow other players to join.<br />
<br />
Please note that currently the editor lacks any permissions system, so all users have access to every function.<br />
<br />
==Plugins & External resources==<br />
{{Main|Resource:Editor/Plugins}}<br />
<br />
The editor allows basic importing of elements from external resources. This is useful for resources that may have to manipulate an element in a specific way that cannot be performed by the editor. For example, a map resource which uses custom models (and has a script to import these models) cannot be manipulated by default within the editor. <br />
<br />
By using the '''import <resourceName>''' command in console the resource's elements can be imported within the editor.<br />
<br />
==FAQ==<br />
==== I get a black screen when launching the Map Editor ====<br />
<br />
Usually this is caused due to incorrect installation of Map Editor resources. If you are using a stable MTASA client, please install it again and make sure that you use Client and Server install option.<br />
<br />
If you are using a nightly build, to get it working right you need to download latest [http://code.google.com/p/multitheftauto/wiki/NightlyBuilds?tm=2 resources (step 3)], unpack the archive and put its contents in:<br />
''MTA San Andreas\server\mods\deathmatch\resources'' , where ''MTA San Andreas'' is a folder where you've installed MTA San Andreas (default location: C:\Program Files\MTA San Andreas).<br />
<br />
Putting them in this path: MTA San Andreas\mods\deathmatch\resources '''is a common mistake''' - it won't work if you put them there. So make sure to put them in the ''italic'' path above.<br />
<br />
<br />
If this issue still occurs, even when you've checked the note above and verified that you've installed it correctly, it might be because you've got an outdated '''acl.xml''' file. You can download the default one [http://multitheftauto.googlecode.com/svn/trunk/MTA10_Server/mods/deathmatch/acl.xml here]. It should be placed in '''server/mods/deathmatch/''' in your MTA: San Andreas installation directory.<br />
<br />
==== I get an "Could not start the local server. See console for details" when using the "Map Editor" button ====<br />
This is because you do not have a valid editor.conf installed. You can download the default one [http://multitheftauto.googlecode.com/svn/trunk/MTA10_Server/mods/deathmatch/editor.conf here]. It should be placed in '''server/mods/deathmatch/''' in your MTA: San Andreas installation directory.<br />
<br />
==== I have saved a map but cannot find it in my server's resources directory, despite the Editor itself being able to see it ====<br />
This is due to the fact that Vista/7 limits write-access for non-admin processes in Program Files directory. Files get written in the "VirtualStore" directory instead of real Program Files folder. You should be able to locate your map resource in a similar directory to:<br />
C:\Users\<USERNAME>\AppData\Local\VirtualStore\Program Files\MTA San Andreas\server\mods\deathmatch\resources\<br />
<br />
Running the Server/MTA San Andreas with Administrative rights will allow the map to be saved to the proper location.<br />
<br />
==== I have some other problem with the map editor ====<br />
<br />
Sometimes resetting the map editor will solve certain issues. The easiest way to do that is install MTA:SA to a brand new folder. Otherwise you can try the following steps:<br />
::1. Go to the resources folder, '''server/mods/deathmatch/resources/''' and delete the '''editor_dump''' directory<br />
::2. Go to the resources folder, '''server/mods/deathmatch/resources/''' and delete the '''editor_test''' directory<br />
<br />
==== I have found a bug or have a suggestion/feedback for the map editor ====<br />
Please use the official [http://bugs.mtasa.com bugtracker] for reporting bugs. Feel free to also join us on [http://www.multitheftauto.com/irc.html IRC].<br />
<br />
[[ru:Resource:Editor]]<br />
[[es:Resource:Editor]]</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/%E8%84%9A%E6%9C%AC%E7%BC%96%E5%86%99%E4%BB%8B%E7%BB%8D&diff=37546ZH-CN/脚本编写介绍2013-11-11T14:43:50Z<p>JoeZhao: </p>
<hr />
<div>对于 MTA 服务器而言，“资源” (Resource) 是十分重要的一个概念。一个资源本身表现为一个包含了一系列文件的文件夹或压缩文件 (zip)，外包含一个用于指示服务器如何加载资源以及资源所包含文件说明的元数据文件 (Meta File)。可把资源的概念视作是运行在操作系统之上的程序 —— 它可以被启动或停止执行，且多个资源可以同时运行在服务器上。<br />
<br />
所谓脚本编程，本质上即是在编写资源。资源可以定义它自身的类型为游戏模式、地图等。MTA 自带一些可供您的游戏模式使用的可选辅助用资源；例如 maplimits，一个用于限制玩家行动范围的资源；或是 deathpickups，用于创建武器拾取物以供辅助死亡竞技 (Deathmatch) 游戏模式。<br />
{{Tip|您应该使用支持 Lua 格式代码的编辑器以编写脚本，以提高脚本编写的效率。我们建议使用 [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] 或 [http://luaedit.sourceforge.net/ LuaEdit]。我们也提供测试版的 [[MTASE|MTA 脚本编辑器]]（目前仍在开发中）。}}<br />
<br />
==创建一个脚本==<br />
第一步，我们将开始一步一步学习如何编写一个能让玩家到处行走的简单脚本。<br />
===脚本都在哪里存放着？===<br />
首先让我们来看看脚本的文件结构。打开 MTA 服务器目录，并定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/<br />
<br />
在该目录下，可以看到一系列 MTA 自带的示例脚本压缩文件。每个压缩文件都是一个 “资源”，在服务器启动时它们会被自动解压并被加载到服务器上运行。若需创建一个新资源，只需在该目录下新建一个任意名称的文件夹。在本教程中我们以 "myserver" 资源作为演示。<br />
<br />
现在请定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/myserver/<br />
<br />
===定义您的资源===<br />
为了能够让服务器得知资源内所包含的数据，每个资源内都必须包含一个位于资源根目录下的 "meta.xml" 文件（本例即 "myserver" 文件夹为资源根目录）。因此我们需要新建该文件，并以记事本方式打开。<br />
<br />
在 "meta.xml" 文件内输入以下的代码：<br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" /><br />
<script src="script.lua" /><br />
</meta><br />
</syntaxhighlight><br />
在 "<info />" 标签中，有一个用于指定资源类型的 "type" 属性。以上代码中指定了该资源类型为 "gamemode"（游戏模式），其他可选的资源类型还有常规包含文件或 "map"（地图），后文将会详细解释。目前只需要知道游戏模式是所有服务器的必不可少的核心，任意服务器都必须要有一个游戏模式。<br />
<br />
"<script />" 标签指明了该资源内所包含的脚本文件，后文将会详细解释。<br />
===创建一个简单的脚本===<br />
注意上例代码中的 "<script />" 标签中并没有将 .lua 文件指定在其他目录路径下，因此现在需要创建一个与 meta.xml 文件同目录下的 .lua 脚本文件；随后，请把以下代码复制到新创建的 script.lua 文件中：<br />
<syntaxhighlight lang="lua"><br />
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10<br />
function joinHandler()<br />
spawnPlayer(source, spawnX, spawnY, spawnZ)<br />
fadeCamera(source, true)<br />
setCameraTarget(source, source)<br />
outputChatBox("Welcome to My Server", source)<br />
end<br />
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)<br />
</syntaxhighlight><br />
当玩家进入服务器后，脚本会将玩家刷到上例代码所指定的出生点坐标 (x, y, z)。注意必须要使用 "fadeCamera" 函数以避免屏幕全黑的情况；同样，DP2 以后的 MTA 版本中，也同样需要使用 "setCameraTarget" 函数以设置玩家摄像机的目标，否则玩家进入服务器后只会见到游戏内蓝色的天空。<br />
<br />
'''source''' 变量表示的是事件的触发者。由于以上代码会在玩家进入服务器时被触发，因此您需要使用该变量以确定是哪位玩家进入了服务器。因此上例代码只会影响到新进入了服务器的玩家，而非服务器内的所有玩家。<br />
<br />
上例代码中，我们可以看到一个 [[addEventHandler]] 函数；从中可看见 3 个参数：'onPlayerJoin'，其表明何时代码会被触发；getRootElement()，其表明了可能的事件触发者（getRootElement() 表示的是游戏内的一切事物或玩家，因此该事件可能是由游戏内的任意事物或玩家所触发的）。以及 joinHandler，其表明哪个函数在该事件 ('onPlayerJoin') 触发后会被执行。其他的代码细节会在后文中详细介绍，现在就启动服务器然后测试一下代码效果吧！<br />
<br />
===执行脚本===<br />
只需要执行 server/ 目录下的可执行文件即可启动服务器。启动服务器后，首先可以从服务器后台上看到一系列的服务器基本信息；注意 port number（端口数）信息，在进入服务器前需要使用到该信息。随后服务器会加载所有位于 mods/deathmatch/resources 目录下的资源，最后会看到提示 "ready to accept connections!"，即表明服务器启动成功。<br />
<br />
在玩家进入服务器前，必须要首先加载游戏模式。在服务器后台输入指令 "start myserver" 并按下回车键发送指令。服务器便会立即启动您刚刚所创建的游戏模式，并列出该游戏模式内所有的脚本代码性错误及警告提示。现在可以启动 MTA 客户端，点击 "Quick Connect" 并输入您在服务器后台上所看到的服务器 IP 地址及端口数。如果没有错误，几秒过后玩家就会出生在 Los Santos。<br />
<br />
接下来，我们将会在脚本中添加一条用于在玩家附近刷出交通工具的游戏指令。您可以跳过本章节并阅读更为高级的[[Map manager|地图管理器]]教程；您也可以阅读[[图形操作界面 (GUI) 脚本编写介绍]]教程以学习如何在 MTA 下创建图形操作界面 (GUI) 及对其进行脚本编写。<br />
<br />
==创建一个简单的游戏指令==<br />
打开先前我们所创建的 "script.lua" 文件。上文提到，我们需要创建一个可在玩家附近刷出交通工具的游戏指令。首先我们需要定义一个用于处理玩家输入指令的函数，以及一个用于创建玩家可从客户端控制台输入游戏指令的指令处理器。<br />
<br />
<syntaxhighlight lang="lua"><br />
-- 定义一个由指令处理器所调用的函数，并提供三个参数：thePlayer, command, vehicleModel<br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- 创建交通工具的代码<br />
end<br />
<br />
-- 创建一个指令处理器<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
"提示：您可以点击示例代码中的函数名以查看该 API 函数的文档。"<br />
<br />
====有关指令处理器====<br />
[[addCommandHandler]] 的第一个参数表明了玩家可以从客户端输入的游戏指令（同时也表明新建了这个游戏指令）；第二个参数是该游戏指令发送到服务端后所调用的函数，本例中该函数名为 "createVehicleForPlayer"。<br />
<br />
如果您有一定的编程经验，您应当知道调用函数的方法是这样的：<br />
<syntaxhighlight lang="lua"><br />
functionName(参数1, 参数2, 参数3, ..)<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
functionName(thePlayer, commandName, argument3, ..)<br />
</syntaxhighlight><br />
看看上例代码，我们发现参数1 为 thePlayer，参数2 为 commandName。thePlayer 表明哪位玩家发送了该游戏指令；而 commandName 表明游戏指令字符串。因此如果玩家发送了指令 "/greet"，commandName 便是 "greet"（不包含指令前面的斜杠 "/")。参数3 是玩家额外的输入，后文中将会提到。<br />
请记住前两个参数（thePlayer 及 commandName）是必不可少的参数，但是您可以随意命名这些参数以符合您的代码风格。<br />
<br />
我们已经调用了 [[addCommandHandler]] 函数；而由于 ''createVehicleForPlayer'' 也同样是一个函数，它也可以以相同的方式被内部所调用。<br />
<br />
For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:<br />
例如：某玩家输入了游戏指令 "createvehicle 468" 以刷出 Sanchez，指令处理器随后会调用 createVehicleForPlayer 函数，然后我们看看这个 createVehicleForPlayer 函数是如何被调用的：<br />
<syntaxhighlight lang="lua"><br />
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer 表示的是输入了 createvehicle 指令的玩家<br />
</syntaxhighlight><br />
可以看到，它提供了几个参数：输入了指令的玩家，指令字符串本身（不包括前面的斜杠 '/'）以及核心指令 createvehicle 以后的任意文本，本例中 "468" 为核心指令以后的文本，其为 Sanchez 交通工具的 ID。所有的指令处理器中，前两个参数都是一样且必须有的（参见 [[addEventHandler]] 文档）。因此，任意的指令处理器中，您都必须得要先定义这两个基本参数，再附加任意数量的附加参数。（附加参数有多少个，核心指令后的附加指令信息就有多少；本例中，createvehicle 有一个表示交通工具 ID 的附加指令信息，因此附加参数数量同为一个）<br />
<br />
"注意：必须要在定义了指令处理函数'''之后'''再创建指令处理器，否则指令处理器届时将无法找到其处理函数。"<br />
<br />
====编写函数====<br />
为了完成我们所创建的函数，我们得先想想我们要在该函数内完成的一些事：<br />
* 获取玩家位置以便知道在何处刷出交通工具（我们希望在玩家身边刷出）<br />
* 计算最理想的交通工具刷出点（我们不希望玩家会卡在车辆内）<br />
* 刷出交通工具<br />
* 检查交通工具是否成功刷出，如果没有则输出错误信息<br />
<br />
为了实现以上的需求，我们需要使用一些 API 函数。可以在[[Script Functions|服务端函数列表]]中找到我们所需的函数。首先我们需要一个用于取得玩家位置的函数。由于玩家属于 “元素” (Element)，我们找到 '''针对元素的 API 函数'''，并找到 [[getElementPosition]] 函数。单击该函数名便可阅读该函数的文档。文档内详细说明了函数的调用语法，返回值以及其示例代码。函数调用语法告诉我们在调用函数时应该提供什么参数。<br />
<br />
[[getElementPosition]] 的调用语法为：<br />
<syntaxhighlight lang="lua"><br />
float, float, float getElementPosition ( element theElement )<br />
</syntaxhighlight><br />
<br />
函数名前的三个 "float" 表示的是返回值类型。本例中表示该函数返回三个浮点数（x、y 及 z）。括号内，可以看到调用该函数时所需提供的参数。本例中只需要传递一个表示欲获取其位置的元素，在这里即玩家。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- 获取玩家位置并将信息放入 x、y 及 z 变量中<br />
-- （local 的意思是定义一个局部变量，在其作用域以外的地方无法访问，本例中即函数作用域）<br />
local x,y,z = getElementPosition(thePlayer)<br />
end<br />
</syntaxhighlight><br />
<br />
下一步，我们希望确保交通工具不会直接刷在玩家所在的位置（这样会玩家卡在车辆内），因此我们把 "x" 变量的值增加了少许，让车辆在距离玩家更东的位置被刷出。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- 获取玩家位置<br />
x = x + 5 -- x 坐标增加 5 个单位<br />
end<br />
</syntaxhighlight><br />
<br />
现在我们需要另一个用于刷出车辆的函数。再次打开 [[Scripting Functions|服务端函数列表]]，这次因为要找的是和交通工具有关的，所以定位到 '''交通工具函数'''，并阅读 [[createVehicle]] 的文档。根据该函数的调用语法，该函数只有一个返回类型（最常见的情况），表示的是创建了的交通工具元素。同样，我们可以看到在调用语法中有一些用方括号 [ ] 括起来的参数，这类参数说明它们是可选的，调用时可以不提供。<br />
<br />
在我们所定义的函数中，一切需要传递给 [[createVehicle]] 函数的参数都准备好了：计算好的 "x, y, z" 变量以及通过玩家输入的游戏指令 "createvehicle 468" 所得到的交通工具 ID，可以通过 ''vehicleModel'' 参数得到该 ID。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- 获取玩家位置<br />
x = x + 5 -- x 坐标增加 5 个单位<br />
-- 创建交通工具并将返回值存入到 ''createdVehicle'' 变量内<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
end<br />
</syntaxhighlight><br />
<br />
当然这些代码还有改善的余地，但至少我们还可以添加一个用于检测交通工具是否成功创建的代码。阅读 [[createVehicle]] 函数文档的 '''返回值''' 部分，该部分说明：若该函数返回 ''false''，则说明交通工具创建失败。因此，我们需要检查 ''createVehicle'' 变量的值以检测交通工具是否创建成功。<br />
<br />
以下是完整的脚本代码：<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- 获取玩家位置<br />
x = x + 5 -- x 坐标增加 5 个单位<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
-- 检查返回值是否为 ''false''<br />
if (createdVehicle == false) then<br />
-- 如果是，将错误信息发送给该特定玩家<br />
outputChatBox("Failed to create vehicle.",thePlayer)<br />
end<br />
end<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
<br />
上例代码中，还介绍了另一个用于发送客户端信息的 [[outputChatBox]] 函数。现在，您应该有能力可以自行阅读 API 函数文档了。若需要进一步学习高级脚本编写，请阅读[[Map manager|地图管理器]]教程。<br />
<br />
==必知==<br />
目前为止，您已经接触到及知悉了有关资源、指令处理器及如何在文档中寻找 API 函数，但要学的还有很多。本节将粗略告诉您有关这些学习内容，您可以自行阅读相关教程。<br />
===客户端及服务端脚本===<br />
您可能曾经了解或是看到过所谓 “客户端及服务端脚本” (Server/Client Script) 的概念或名称了。事实上，您不仅能够编写典型的运行在服务器之上的，用于提供游戏指令处理等需求的脚本；还能够编写运行在 MTA 玩家客户端之上的脚本。之可以编写客户端脚本，原因是一些 MTA 所提供的特殊功能只能在客户端上执行（例如图形操作界面），或是在客户端上执行一些代码比在服务端上执行效率要高些。<br />
<br />
大部分您所制作的资源（游戏模式、地图）可能都是服务端脚本，例如本教程前面所介绍的脚本。但如果您所编写的代码无法在服务端上执行，则您可能需要令其可在客户端上运行（即编写客户端脚本）。若要开始尝试编写一个客户端脚本，您需要创建一个脚本文件（例如，把它命名为 ''client.lua''），并修改 meta.xml 如下：<br />
<syntaxhighlight lang="xml"><br />
<script src="client.lua" type="client" /><br />
</syntaxhighlight><br />
''type'' 属性默认值为 'server'（即默认服务端脚本），因此只有在需要指定其是客户端脚本时才显式指定 ''type'' 属性。一个脚本文件一旦其 ''type'' 属性的值设置为 ''client''，则玩家连接到服务器时，该脚本文件会自动下载到玩家客户端。有关更多信息，请阅读[[客户端脚本]]教程。<br />
<br />
===更复杂的资源===<br />
上一节简单介绍了如何添加一个客户端脚本，但其实您什么都可以做到。正如本教程开头提到过，资源可以是任何类型的游戏模块。这些资源本身做什么或提供什么功能，便决定了它们的类型是什么。首先我们来分析一下下面的这些资源：<br />
<br />
====第一个示例资源 —— 辅助类资源====<br />
<syntaxhighlight lang="xml"><br />
/admin_commands<br />
/meta.xml<br />
/commands.lua<br />
/client.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="admin commands" /><br />
<script src="commands.lua" /><br />
<script src="client.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* ''commands.lua'' 提供一些管理员指令，例如封禁玩家、玩家禁言等<br />
* ''client.lua'' 提供图形操作界面以简化玩家操作<br />
<br />
该示例资源可以随时被使用（也可以设置为随服务器而自动启动），原因是该资源对于整个游戏流程而言有一定的帮助（管理服务器）且不会影响到正常的游戏过程。<br />
<br />
====第二个示例资源 —— 游戏模式====<br />
<syntaxhighlight lang="xml"><br />
/counterstrike<br />
/meta.xml<br />
/counterstrike.lua<br />
/buymenu.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike remake" type="gamemode" /><br />
<script src="counterstrike.lua" /><br />
<script src="buymenu.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* ''counterstrike.lua'' 包含有类似于以下功能的实现：<br />
** 允许玩家选择其团队并刷出玩家<br />
** 把武器、目标及游戏指示提供给玩家<br />
** 规定游戏规则。例如：一盘游戏的时间、玩家死后会发生什么等<br />
** 等等等等...<br />
* ''buymenu.lua'' 是一个客户端脚本，其用于创建武器购买菜单（使用到了图形操作界面，因此必须写为客户端脚本）<br />
<br />
该示例资源便是一个游戏模式，因为它不但影响到了游戏过程，还实际规定了''游戏规则''。该资源的 ''type'' 属性表明了该资源是运行在[[地图管理器]]上的，但 QA 团队编写的另一个资源可以用于帮助您管理游戏模式以及地图加载。强烈建议您在该辅助资源的基础上编写您的游戏模式。<br />
<br />
这可能也说明了游戏模式在没有地图的情况下无法运行。游戏模式本身就应该包含有至少一个地图。下一个示例将会介绍地图。<br />
<br />
====第三个示例 —— 地图====<br />
<syntaxhighlight lang="xml"><br />
/cs-airport<br />
/meta.xml<br />
/airport.map<br />
/airport.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" /><br />
<map src="airport.map" /><br />
<script src="airport.lua" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* XML 格式的 ''airport.map'' 文件向游戏模式提供了有关该地图的信息，包括：<br />
** 玩家的出生点、出生时配备的武器，以及玩家所属的团队<br />
** 玩家的目标<br />
** 天气、世界时间、时间限制<br />
** 提供交通工具<br />
* ''airport.lua'' 可能包含了一些辅助地图自身的功能：<br />
** 当特定的事情发生时打开特定的门或使某物爆炸<br />
** 创建或移动一些自定义对象，或是控制通过 .map 文件所创建的对象<br />
** 等等等等...<br />
<br />
正如您所见的，''type'' 属性改为了 'map'，告诉[[地图管理器]]该资源为地图；而 ''gamemodes'' 属性指明了该地图只有在什么游戏模式下才能够运行，在本例中所指定的游戏模式即上面所创建的。<br />
地图资源内也可以包含脚本。当然，地图并不一定需要包含脚本，但是这可以在游戏模式所设计的游戏规则以外再允许地图创造者设计这些地图自己的游戏规则。<br />
<br />
''airport.map'' 文件内容可能如下：<br />
<syntaxhighlight lang="xml"><br />
<map mode="deathmatch" version="1.0"><br />
<terrorists><br />
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" /><br />
</terrorists><br />
<counterterrorists><br />
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" /><br />
</counterterrorists><br />
<br />
<bomb posX="23342.23" posY="" posZ="" /><br />
<br />
<vehicle posX="" posY="" posZ="" model="602" /> <br />
<vehicle posX="" posY="" posZ="" model="603" /> <br />
</map><br />
</syntaxhighlight><br />
<br />
当游戏模式及地图同时被加载，地图管理器会自动启动地图资源，随后游戏模式资源会开始读取地图信息；当切换到其他地图时，当前的地图资源会被停止，然后轮到下一张地图资源被加载。请阅读[[编写游戏模式]]教程以学习更深入的地图资源管理模式。<br />
<br />
===事件===<br />
MTA 会以触发事件的形式告知脚本发生了什么。例如，当任意玩家死亡时，[[onPlayerWasted]] 事件会被触发。为了能够及时地在任意玩家死亡时能够执行一些操作，您需要自定义一个用于处理该类型事件的事件处理器。<br />
<br />
下列示例代码会在任意玩家死后，向所有玩家发送该玩家死亡的信息：<br />
<syntaxhighlight lang="lua"><br />
function playerDied(totalAmmo, killer, killerWeapon, bodypart)<br />
outputChatBox(getPlayerName(source).." died!")<br />
end<br />
addEventHandler("onPlayerWasted",getRootElement(),playerDied)<br />
</syntaxhighlight><br />
<br />
事件文档列举了不同事件触发后将会传递到事件处理函数的不同参数。请留意 ''source'' 变量，虽然其并非是参数，但每个处理函数都隐式包含有该变量。在不同的事件中，该变量表示的概念不同；例如玩家事件的处理函数中，该变量表示触发了事件的玩家元素。<br />
<br />
==然后呢？==<br />
现在，您应该已经大概了解了 MTA 脚本编写的一些基础知识以及如何阅读文档了。[[首页]]提供有更多的信息、教程以及参考链接。您可以随时阅读这些文章以更深入地学习 MTA 脚本编写。<br />
{{note|强烈建议您开始阅读[[调试脚本]]教程。编写脚本时，调试是十分有必要的；我们也建议您参考[[预定义变量列表]]中的信息以帮助您更高效率地编写 MTA 脚本。}}<br />
'''See also:'''<br />
* [[Advanced Topics]]<br />
[[es:Introducción a la Programación]]<br />
[[it:Introduzione allo scripting]]<br />
[[nl:Scripting_introductie]]<br />
[[pt-br:Introdução ao Scripting]]<br />
[[ru:Scripting Introduction]]<br />
[[ar:مقدمه_في_البرمجه]]</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/%E8%84%9A%E6%9C%AC%E7%BC%96%E5%86%99%E4%BB%8B%E7%BB%8D&diff=37545ZH-CN/脚本编写介绍2013-11-11T14:42:11Z<p>JoeZhao: </p>
<hr />
<div>对于 MTA 服务器而言，“资源” (Resource) 是十分重要的一个概念。一个资源本身表现为一个包含了一系列文件的文件夹或压缩文件 (zip)，外包含一个用于指示服务器如何加载资源以及资源所包含文件说明的元数据文件 (Meta File)。可把资源的概念视作是运行在操作系统之上的程序 —— 它可以被启动或停止执行，且多个资源可以同时运行在服务器上。<br />
<br />
所谓脚本编程，本质上即是在编写资源。资源可以定义它自身的类型为游戏模式、地图等。MTA 自带一些可供您的游戏模式使用的可选辅助用资源；例如 maplimits，一个用于限制玩家行动范围的资源；或是 deathpickups，用于创建武器拾取物以供辅助死亡竞技 (Deathmatch) 游戏模式。<br />
{{Tip|您应该使用支持 Lua 格式代码的编辑器以编写脚本，以提高脚本编写的效率。我们建议使用 [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] 或 [http://luaedit.sourceforge.net/ LuaEdit]。我们也提供测试版的 [[MTASE|MTA 脚本编辑器]]（目前仍在开发中）。}}<br />
<br />
==创建一个脚本==<br />
第一步，我们将开始一步一步学习如何编写一个能让玩家到处行走的简单脚本。<br />
===脚本都在哪里存放着？===<br />
首先让我们来看看脚本的文件结构。打开 MTA 服务器目录，并定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/<br />
<br />
在该目录下，可以看到一系列 MTA 自带的示例脚本压缩文件。每个压缩文件都是一个 “资源”，在服务器启动时它们会被自动解压并被加载到服务器上运行。若需创建一个新资源，只需在该目录下新建一个任意名称的文件夹。在本教程中我们以 "myserver" 资源作为演示。<br />
<br />
现在请定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/myserver/<br />
<br />
===定义您的资源===<br />
为了能够让服务器得知资源内所包含的数据，每个资源内都必须包含一个位于资源根目录下的 "meta.xml" 文件（本例即 "myserver" 文件夹为资源根目录）。因此我们需要新建该文件，并以记事本方式打开。<br />
<br />
在 "meta.xml" 文件内输入以下的代码：<br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" /><br />
<script src="script.lua" /><br />
</meta><br />
</syntaxhighlight><br />
在 "<info />" 标签中，有一个用于指定资源类型的 "type" 属性。以上代码中指定了该资源类型为 "gamemode"（游戏模式），其他可选的资源类型还有常规包含文件或 "map"（地图），后文将会详细解释。目前只需要知道游戏模式是所有服务器的必不可少的核心，任意服务器都必须要有一个游戏模式。<br />
<br />
"<script />" 标签指明了该资源内所包含的脚本文件，后文将会详细解释。<br />
===创建一个简单的脚本===<br />
注意上例代码中的 "<script />" 标签中并没有将 .lua 文件指定在其他目录路径下，因此现在需要创建一个与 meta.xml 文件同目录下的 .lua 脚本文件；随后，请把以下代码复制到新创建的 script.lua 文件中：<br />
<syntaxhighlight lang="lua"><br />
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10<br />
function joinHandler()<br />
spawnPlayer(source, spawnX, spawnY, spawnZ)<br />
fadeCamera(source, true)<br />
setCameraTarget(source, source)<br />
outputChatBox("Welcome to My Server", source)<br />
end<br />
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)<br />
</syntaxhighlight><br />
当玩家进入服务器后，脚本会将玩家刷到上例代码所指定的出生点坐标 (x, y, z)。注意必须要使用 "fadeCamera" 函数以避免屏幕全黑的情况；同样，DP2 以后的 MTA 版本中，也同样需要使用 "setCameraTarget" 函数以设置玩家摄像机的目标，否则玩家进入服务器后只会见到游戏内蓝色的天空。<br />
<br />
'''source''' 变量表示的是事件的触发者。由于以上代码会在玩家进入服务器时被触发，因此您需要使用该变量以确定是哪位玩家进入了服务器。因此上例代码只会影响到新进入了服务器的玩家，而非服务器内的所有玩家。<br />
<br />
上例代码中，我们可以看到一个 [[addEventHandler]] 函数；从中可看见 3 个参数：'onPlayerJoin'，其表明何时代码会被触发；getRootElement()，其表明了可能的事件触发者（getRootElement() 表示的是游戏内的一切事物或玩家，因此该事件可能是由游戏内的任意事物或玩家所触发的）。以及 joinHandler，其表明哪个函数在该事件 ('onPlayerJoin') 触发后会被执行。其他的代码细节会在后文中详细介绍，现在就启动服务器然后测试一下代码效果吧！<br />
<br />
===执行脚本===<br />
只需要执行 server/ 目录下的可执行文件即可启动服务器。启动服务器后，首先可以从服务器后台上看到一系列的服务器基本信息；注意 port number（端口数）信息，在进入服务器前需要使用到该信息。随后服务器会加载所有位于 mods/deathmatch/resources 目录下的资源，最后会看到提示 "ready to accept connections!"，即表明服务器启动成功。<br />
<br />
在玩家进入服务器前，必须要首先加载游戏模式。在服务器后台输入指令 "start myserver" 并按下回车键发送指令。服务器便会立即启动您刚刚所创建的游戏模式，并列出该游戏模式内所有的脚本代码性错误及警告提示。现在可以启动 MTA 客户端，点击 "Quick Connect" 并输入您在服务器后台上所看到的服务器 IP 地址及端口数。如果没有错误，几秒过后玩家就会出生在 Los Santos。<br />
<br />
接下来，我们将会在脚本中添加一条用于在玩家附近刷出交通工具的游戏指令。您可以跳过本章节并阅读更为高级的[[Map manager|地图管理器]]教程；您也可以阅读[[图形操作界面 (GUI) 脚本编写介绍]]教程以学习如何在 MTA 下创建图形操作界面 (GUI) 及对其进行脚本编写。<br />
<br />
==创建一个简单的游戏指令==<br />
打开先前我们所创建的 "script.lua" 文件。上文提到，我们需要创建一个可在玩家附近刷出交通工具的游戏指令。首先我们需要定义一个用于处理玩家输入指令的函数，以及一个用于创建玩家可从客户端控制台输入游戏指令的指令处理器。<br />
<br />
<syntaxhighlight lang="lua"><br />
-- 定义一个由指令处理器所调用的函数，并提供三个参数：thePlayer, command, vehicleModel<br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- 创建交通工具的代码<br />
end<br />
<br />
-- 创建一个指令处理器<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
"提示：您可以点击示例代码中的函数名以查看该 API 函数的文档。"<br />
<br />
====有关指令处理器====<br />
[[addCommandHandler]] 的第一个参数表明了玩家可以从客户端输入的游戏指令（同时也表明新建了这个游戏指令）；第二个参数是该游戏指令发送到服务端后所调用的函数，本例中该函数名为 "createVehicleForPlayer"。<br />
<br />
如果您有一定的编程经验，您应当知道调用函数的方法是这样的：<br />
<syntaxhighlight lang="lua"><br />
functionName(参数1, 参数2, 参数3, ..)<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
functionName(thePlayer, commandName, argument3, ..)<br />
</syntaxhighlight><br />
看看上例代码，我们发现参数1 为 thePlayer，参数2 为 commandName。thePlayer 表明哪位玩家发送了该游戏指令；而 commandName 表明游戏指令字符串。因此如果玩家发送了指令 "/greet"，commandName 便是 "greet"（不包含指令前面的斜杠 "/")。参数3 是玩家额外的输入，后文中将会提到。<br />
请记住前两个参数（thePlayer 及 commandName）是必不可少的参数，但是您可以随意命名这些参数以符合您的代码风格。<br />
<br />
We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.<br />
我们已经调用了 [[addCommandHandler]] 函数<br />
<br />
For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:<br />
例如：某玩家输入了游戏指令 "createvehicle 468" 以刷出 Sanchez，指令处理器随后会调用 createVehicleForPlayer 函数，然后我们看看这个 createVehicleForPlayer 函数是如何被调用的：<br />
<syntaxhighlight lang="lua"><br />
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer 表示的是输入了 createvehicle 指令的玩家<br />
</syntaxhighlight><br />
可以看到，它提供了几个参数：输入了指令的玩家，指令字符串本身（不包括前面的斜杠 '/'）以及核心指令 createvehicle 以后的任意文本，本例中 "468" 为核心指令以后的文本，其为 Sanchez 交通工具的 ID。所有的指令处理器中，前两个参数都是一样且必须有的（参见 [[addEventHandler]] 文档）。因此，任意的指令处理器中，您都必须得要先定义这两个基本参数，再附加任意数量的附加参数。（附加参数有多少个，核心指令后的附加指令信息就有多少；本例中，createvehicle 有一个表示交通工具 ID 的附加指令信息，因此附加参数数量同为一个）<br />
<br />
"注意：必须要在定义了指令处理函数'''之后'''再创建指令处理器，否则指令处理器届时将无法找到其处理函数。"<br />
<br />
====编写函数====<br />
为了完成我们所创建的函数，我们得先想想我们要在该函数内完成的一些事：<br />
* 获取玩家位置以便知道在何处刷出交通工具（我们希望在玩家身边刷出）<br />
* 计算最理想的交通工具刷出点（我们不希望玩家会卡在车辆内）<br />
* 刷出交通工具<br />
* 检查交通工具是否成功刷出，如果没有则输出错误信息<br />
<br />
为了实现以上的需求，我们需要使用一些 API 函数。可以在[[Script Functions|服务端函数列表]]中找到我们所需的函数。首先我们需要一个用于取得玩家位置的函数。由于玩家属于 “元素” (Element)，我们找到 '''针对元素的 API 函数'''，并找到 [[getElementPosition]] 函数。单击该函数名便可阅读该函数的文档。文档内详细说明了函数的调用语法，返回值以及其示例代码。函数调用语法告诉我们在调用函数时应该提供什么参数。<br />
<br />
[[getElementPosition]] 的调用语法为：<br />
<syntaxhighlight lang="lua"><br />
float, float, float getElementPosition ( element theElement )<br />
</syntaxhighlight><br />
<br />
函数名前的三个 "float" 表示的是返回值类型。本例中表示该函数返回三个浮点数（x、y 及 z）。括号内，可以看到调用该函数时所需提供的参数。本例中只需要传递一个表示欲获取其位置的元素，在这里即玩家。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- 获取玩家位置并将信息放入 x、y 及 z 变量中<br />
-- （local 的意思是定义一个局部变量，在其作用域以外的地方无法访问，本例中即函数作用域）<br />
local x,y,z = getElementPosition(thePlayer)<br />
end<br />
</syntaxhighlight><br />
<br />
下一步，我们希望确保交通工具不会直接刷在玩家所在的位置（这样会玩家卡在车辆内），因此我们把 "x" 变量的值增加了少许，让车辆在距离玩家更东的位置被刷出。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- 获取玩家位置<br />
x = x + 5 -- x 坐标增加 5 个单位<br />
end<br />
</syntaxhighlight><br />
<br />
现在我们需要另一个用于刷出车辆的函数。再次打开 [[Scripting Functions|服务端函数列表]]，这次因为要找的是和交通工具有关的，所以定位到 '''交通工具函数'''，并阅读 [[createVehicle]] 的文档。根据该函数的调用语法，该函数只有一个返回类型（最常见的情况），表示的是创建了的交通工具元素。同样，我们可以看到在调用语法中有一些用方括号 [ ] 括起来的参数，这类参数说明它们是可选的，调用时可以不提供。<br />
<br />
在我们所定义的函数中，一切需要传递给 [[createVehicle]] 函数的参数都准备好了：计算好的 "x, y, z" 变量以及通过玩家输入的游戏指令 "createvehicle 468" 所得到的交通工具 ID，可以通过 ''vehicleModel'' 参数得到该 ID。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- 获取玩家位置<br />
x = x + 5 -- x 坐标增加 5 个单位<br />
-- 创建交通工具并将返回值存入到 ''createdVehicle'' 变量内<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
end<br />
</syntaxhighlight><br />
<br />
当然这些代码还有改善的余地，但至少我们还可以添加一个用于检测交通工具是否成功创建的代码。阅读 [[createVehicle]] 函数文档的 '''返回值''' 部分，该部分说明：若该函数返回 ''false''，则说明交通工具创建失败。因此，我们需要检查 ''createVehicle'' 变量的值以检测交通工具是否创建成功。<br />
<br />
以下是完整的脚本代码：<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- 获取玩家位置<br />
x = x + 5 -- x 坐标增加 5 个单位<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
-- 检查返回值是否为 ''false''<br />
if (createdVehicle == false) then<br />
-- 如果是，将错误信息发送给该特定玩家<br />
outputChatBox("Failed to create vehicle.",thePlayer)<br />
end<br />
end<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
<br />
上例代码中，还介绍了另一个用于发送客户端信息的 [[outputChatBox]] 函数。现在，您应该有能力可以自行阅读 API 函数文档了。若需要进一步学习高级脚本编写，请阅读[[Map manager|地图管理器]]教程。<br />
<br />
==必知==<br />
目前为止，您已经接触到及知悉了有关资源、指令处理器及如何在文档中寻找 API 函数，但要学的还有很多。本节将粗略告诉您有关这些学习内容，您可以自行阅读相关教程。<br />
===客户端及服务端脚本===<br />
您可能曾经了解或是看到过所谓 “客户端及服务端脚本” (Server/Client Script) 的概念或名称了。事实上，您不仅能够编写典型的运行在服务器之上的，用于提供游戏指令处理等需求的脚本；还能够编写运行在 MTA 玩家客户端之上的脚本。之可以编写客户端脚本，原因是一些 MTA 所提供的特殊功能只能在客户端上执行（例如图形操作界面），或是在客户端上执行一些代码比在服务端上执行效率要高些。<br />
<br />
大部分您所制作的资源（游戏模式、地图）可能都是服务端脚本，例如本教程前面所介绍的脚本。但如果您所编写的代码无法在服务端上执行，则您可能需要令其可在客户端上运行（即编写客户端脚本）。若要开始尝试编写一个客户端脚本，您需要创建一个脚本文件（例如，把它命名为 ''client.lua''），并修改 meta.xml 如下：<br />
<syntaxhighlight lang="xml"><br />
<script src="client.lua" type="client" /><br />
</syntaxhighlight><br />
''type'' 属性默认值为 'server'（即默认服务端脚本），因此只有在需要指定其是客户端脚本时才显式指定 ''type'' 属性。一个脚本文件一旦其 ''type'' 属性的值设置为 ''client''，则玩家连接到服务器时，该脚本文件会自动下载到玩家客户端。有关更多信息，请阅读[[客户端脚本]]教程。<br />
<br />
===更复杂的资源===<br />
上一节简单介绍了如何添加一个客户端脚本，但其实您什么都可以做到。正如本教程开头提到过，资源可以是任何类型的游戏模块。这些资源本身做什么或提供什么功能，便决定了它们的类型是什么。首先我们来分析一下下面的这些资源：<br />
<br />
====第一个示例资源 —— 辅助类资源====<br />
<syntaxhighlight lang="xml"><br />
/admin_commands<br />
/meta.xml<br />
/commands.lua<br />
/client.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="admin commands" /><br />
<script src="commands.lua" /><br />
<script src="client.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* ''commands.lua'' 提供一些管理员指令，例如封禁玩家、玩家禁言等<br />
* ''client.lua'' 提供图形操作界面以简化玩家操作<br />
<br />
该示例资源可以随时被使用（也可以设置为随服务器而自动启动），原因是该资源对于整个游戏流程而言有一定的帮助（管理服务器）且不会影响到正常的游戏过程。<br />
<br />
====第二个示例资源 —— 游戏模式====<br />
<syntaxhighlight lang="xml"><br />
/counterstrike<br />
/meta.xml<br />
/counterstrike.lua<br />
/buymenu.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike remake" type="gamemode" /><br />
<script src="counterstrike.lua" /><br />
<script src="buymenu.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* ''counterstrike.lua'' 包含有类似于以下功能的实现：<br />
** 允许玩家选择其团队并刷出玩家<br />
** 把武器、目标及游戏指示提供给玩家<br />
** 规定游戏规则。例如：一盘游戏的时间、玩家死后会发生什么等<br />
** 等等等等...<br />
* ''buymenu.lua'' 是一个客户端脚本，其用于创建武器购买菜单（使用到了图形操作界面，因此必须写为客户端脚本）<br />
<br />
该示例资源便是一个游戏模式，因为它不但影响到了游戏过程，还实际规定了''游戏规则''。该资源的 ''type'' 属性表明了该资源是运行在[[地图管理器]]上的，但 QA 团队编写的另一个资源可以用于帮助您管理游戏模式以及地图加载。强烈建议您在该辅助资源的基础上编写您的游戏模式。<br />
<br />
这可能也说明了游戏模式在没有地图的情况下无法运行。游戏模式本身就应该包含有至少一个地图。下一个示例将会介绍地图。<br />
<br />
====第三个示例 —— 地图====<br />
<syntaxhighlight lang="xml"><br />
/cs-airport<br />
/meta.xml<br />
/airport.map<br />
/airport.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" /><br />
<map src="airport.map" /><br />
<script src="airport.lua" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* XML 格式的 ''airport.map'' 文件向游戏模式提供了有关该地图的信息，包括：<br />
** 玩家的出生点、出生时配备的武器，以及玩家所属的团队<br />
** 玩家的目标<br />
** 天气、世界时间、时间限制<br />
** 提供交通工具<br />
* ''airport.lua'' 可能包含了一些辅助地图自身的功能：<br />
** 当特定的事情发生时打开特定的门或使某物爆炸<br />
** 创建或移动一些自定义对象，或是控制通过 .map 文件所创建的对象<br />
** 等等等等...<br />
<br />
正如您所见的，''type'' 属性改为了 'map'，告诉[[地图管理器]]该资源为地图；而 ''gamemodes'' 属性指明了该地图只有在什么游戏模式下才能够运行，在本例中所指定的游戏模式即上面所创建的。<br />
地图资源内也可以包含脚本。当然，地图并不一定需要包含脚本，但是这可以在游戏模式所设计的游戏规则以外再允许地图创造者设计这些地图自己的游戏规则。<br />
<br />
''airport.map'' 文件内容可能如下：<br />
<syntaxhighlight lang="xml"><br />
<map mode="deathmatch" version="1.0"><br />
<terrorists><br />
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" /><br />
</terrorists><br />
<counterterrorists><br />
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" /><br />
</counterterrorists><br />
<br />
<bomb posX="23342.23" posY="" posZ="" /><br />
<br />
<vehicle posX="" posY="" posZ="" model="602" /> <br />
<vehicle posX="" posY="" posZ="" model="603" /> <br />
</map><br />
</syntaxhighlight><br />
<br />
当游戏模式及地图同时被加载，地图管理器会自动启动地图资源，随后游戏模式资源会开始读取地图信息；当切换到其他地图时，当前的地图资源会被停止，然后轮到下一张地图资源被加载。请阅读[[编写游戏模式]]教程以学习更深入的地图资源管理模式。<br />
<br />
===事件===<br />
MTA 会以触发事件的形式告知脚本发生了什么。例如，当任意玩家死亡时，[[onPlayerWasted]] 事件会被触发。为了能够及时地在任意玩家死亡时能够执行一些操作，您需要自定义一个用于处理该类型事件的事件处理器。<br />
<br />
下列示例代码会在任意玩家死后，向所有玩家发送该玩家死亡的信息：<br />
<syntaxhighlight lang="lua"><br />
function playerDied(totalAmmo, killer, killerWeapon, bodypart)<br />
outputChatBox(getPlayerName(source).." died!")<br />
end<br />
addEventHandler("onPlayerWasted",getRootElement(),playerDied)<br />
</syntaxhighlight><br />
<br />
事件文档列举了不同事件触发后将会传递到事件处理函数的不同参数。请留意 ''source'' 变量，虽然其并非是参数，但每个处理函数都隐式包含有该变量。在不同的事件中，该变量表示的概念不同；例如玩家事件的处理函数中，该变量表示触发了事件的玩家元素。<br />
<br />
==然后呢？==<br />
现在，您应该已经大概了解了 MTA 脚本编写的一些基础知识以及如何阅读文档了。[[首页]]提供有更多的信息、教程以及参考链接。您可以随时阅读这些文章以更深入地学习 MTA 脚本编写。<br />
{{note|强烈建议您开始阅读[[调试脚本]]教程。编写脚本时，调试是十分有必要的；我们也建议您参考[[预定义变量列表]]中的信息以帮助您更高效率地编写 MTA 脚本。}}<br />
'''See also:'''<br />
* [[Advanced Topics]]<br />
[[es:Introducción a la Programación]]<br />
[[it:Introduzione allo scripting]]<br />
[[nl:Scripting_introductie]]<br />
[[pt-br:Introdução ao Scripting]]<br />
[[ru:Scripting Introduction]]<br />
[[ar:مقدمه_في_البرمجه]]</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/%E8%84%9A%E6%9C%AC%E7%BC%96%E5%86%99%E4%BB%8B%E7%BB%8D&diff=37544ZH-CN/脚本编写介绍2013-11-11T14:21:16Z<p>JoeZhao: </p>
<hr />
<div>对于 MTA 服务器而言，“资源” (Resource) 是十分重要的一个概念。一个资源本身表现为一个包含了一系列文件的文件夹或压缩文件 (zip)，外包含一个用于指示服务器如何加载资源以及资源所包含文件说明的元数据文件 (Meta File)。可把资源的概念视作是运行在操作系统之上的程序 —— 它可以被启动或停止执行，且多个资源可以同时运行在服务器上。<br />
<br />
所谓脚本编程，本质上即是在编写资源。资源可以定义它自身的类型为游戏模式、地图等。MTA 自带一些可供您的游戏模式使用的可选辅助用资源；例如 maplimits，一个用于限制玩家行动范围的资源；或是 deathpickups，用于创建武器拾取物以供辅助死亡竞技 (Deathmatch) 游戏模式。<br />
{{Tip|您应该使用支持 Lua 格式代码的编辑器以编写脚本，以提高脚本编写的效率。我们建议使用 [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] 或 [http://luaedit.sourceforge.net/ LuaEdit]。我们也提供测试版的 [[MTASE|MTA 脚本编辑器]]（目前仍在开发中）。}}<br />
<br />
==创建一个脚本==<br />
第一步，我们将开始一步一步学习如何编写一个能让玩家到处行走的简单脚本。<br />
===脚本都在哪里存放着？===<br />
首先让我们来看看脚本的文件结构。打开 MTA 服务器目录，并定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/<br />
<br />
在该目录下，可以看到一系列 MTA 自带的示例脚本压缩文件。每个压缩文件都是一个 “资源”，在服务器启动时它们会被自动解压并被加载到服务器上运行。若需创建一个新资源，只需在该目录下新建一个任意名称的文件夹。在本教程中我们以 "myserver" 资源作为演示。<br />
<br />
现在请定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/myserver/<br />
<br />
===定义您的资源===<br />
为了能够让服务器得知资源内所包含的数据，每个资源内都必须包含一个位于资源根目录下的 "meta.xml" 文件（本例即 "myserver" 文件夹为资源根目录）。因此我们需要新建该文件，并以记事本方式打开。<br />
<br />
在 "meta.xml" 文件内输入以下的代码：<br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" /><br />
<script src="script.lua" /><br />
</meta><br />
</syntaxhighlight><br />
在 "<info />" 标签中，有一个用于指定资源类型的 "type" 属性。以上代码中指定了该资源类型为 "gamemode"（游戏模式），其他可选的资源类型还有常规包含文件或 "map"（地图），后文将会详细解释。目前只需要知道游戏模式是所有服务器的必不可少的核心，任意服务器都必须要有一个游戏模式。<br />
<br />
"<script />" 标签指明了该资源内所包含的脚本文件，后文将会详细解释。<br />
===创建一个简单的脚本===<br />
注意上例代码中的 "<script />" 标签中并没有将 .lua 文件指定在其他目录路径下，因此现在需要创建一个与 meta.xml 文件同目录下的 .lua 脚本文件；随后，请把以下代码复制到新创建的 script.lua 文件中：<br />
<syntaxhighlight lang="lua"><br />
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10<br />
function joinHandler()<br />
spawnPlayer(source, spawnX, spawnY, spawnZ)<br />
fadeCamera(source, true)<br />
setCameraTarget(source, source)<br />
outputChatBox("Welcome to My Server", source)<br />
end<br />
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)<br />
</syntaxhighlight><br />
当玩家进入服务器后，脚本会将玩家刷到上例代码所指定的出生点坐标 (x, y, z)。注意必须要使用 "fadeCamera" 函数以避免屏幕全黑的情况；同样，DP2 以后的 MTA 版本中，也同样需要使用 "setCameraTarget" 函数以设置玩家摄像机的目标，否则玩家进入服务器后只会见到游戏内蓝色的天空。<br />
<br />
'''source''' 变量表示的是事件的触发者。由于以上代码会在玩家进入服务器时被触发，因此您需要使用该变量以确定是哪位玩家进入了服务器。因此上例代码只会影响到新进入了服务器的玩家，而非服务器内的所有玩家。<br />
<br />
上例代码中，我们可以看到一个 [[addEventHandler]] 函数；从中可看见 3 个参数：'onPlayerJoin'，其表明何时代码会被触发；getRootElement()，其表明了可能的事件触发者（getRootElement() 表示的是游戏内的一切事物或玩家，因此该事件可能是由游戏内的任意事物或玩家所触发的）。以及 joinHandler，其表明哪个函数在该事件 ('onPlayerJoin') 触发后会被执行。其他的代码细节会在后文中详细介绍，现在就启动服务器然后测试一下代码效果吧！<br />
<br />
===执行脚本===<br />
只需要执行 server/ 目录下的可执行文件即可启动服务器。启动服务器后，首先可以从服务器后台上看到一系列的服务器基本信息；注意 port number（端口数）信息，在进入服务器前需要使用到该信息。随后服务器会加载所有位于 mods/deathmatch/resources 目录下的资源，最后会看到提示 "ready to accept connections!"，即表明服务器启动成功。<br />
<br />
在玩家进入服务器前，必须要首先加载游戏模式。在服务器后台输入指令 "start myserver" 并按下回车键发送指令。服务器便会立即启动您刚刚所创建的游戏模式，并列出该游戏模式内所有的脚本代码性错误及警告提示。现在可以启动 MTA 客户端，点击 "Quick Connect" 并输入您在服务器后台上所看到的服务器 IP 地址及端口数。如果没有错误，几秒过后玩家就会出生在 Los Santos。<br />
<br />
接下来，我们将会在脚本中添加一条用于在玩家附近刷出交通工具的游戏指令。您可以跳过本章节并阅读更为高级的[[Map manager|地图管理器]]教程；您也可以阅读[[图形操作界面 (GUI) 脚本编写介绍]]教程以学习如何在 MTA 下创建图形操作界面 (GUI) 及对其进行脚本编写。<br />
<br />
==创建一个简单的游戏指令==<br />
打开先前我们所创建的 "script.lua" 文件。上文提到，我们需要创建一个可在玩家附近刷出交通工具的游戏指令。首先我们需要定义一个用于处理玩家输入指令的函数，以及一个用于创建玩家可从客户端控制台输入游戏指令的指令处理器。<br />
<br />
<syntaxhighlight lang="lua"><br />
-- 定义一个由指令处理器所调用的函数，并提供三个参数：thePlayer, command, vehicleModel<br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- 创建交通工具的代码<br />
end<br />
<br />
-- 创建一个指令处理器<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
"提示：您可以点击示例代码中的函数名以查看该 API 函数的文档。"<br />
<br />
====有关指令处理器====<br />
[[addCommandHandler]] 的第一个参数表明了玩家可以从客户端输入的游戏指令（同时也表明新建了这个游戏指令）；第二个参数是该游戏指令发送到服务端后所调用的函数，本例中该函数名为 "createVehicleForPlayer"。<br />
<br />
如果您有一定的编程经验，您应当知道调用函数的方法是这样的：<br />
<syntaxhighlight lang="lua"><br />
functionName(参数1, 参数2, 参数3, ..)<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
functionName(thePlayer, commandName, argument3, ..)<br />
</syntaxhighlight><br />
看看上例代码，我们发现参数1 为 thePlayer，参数2 为 commandName。thePlayer 表明哪位玩家发送了该游戏指令；而 commandName 表明游戏指令字符串。因此如果玩家发送了指令 "/greet"，commandName 便是 "greet"（不包含指令前面的斜杠 "/")。参数3 是玩家额外的输入，后文中将会提到。<br />
请记住前两个参数（thePlayer 及 commandName）是必不可少的参数，但是您可以随意命名这些参数以符合您的代码风格。<br />
<br />
We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.<br />
我们已经调用了 [[addCommandHandler]] 函数<br />
<br />
For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:<br />
例如：某玩家输入了游戏指令 "createvehicle 468" 以刷出 Sanchez，指令处理器随后会调用 createVehicleForPlayer 函数，然后我们看看这个 createVehicleForPlayer 函数是如何被调用的：<br />
<syntaxhighlight lang="lua"><br />
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer 表示的是输入了 createvehicle 指令的玩家<br />
</syntaxhighlight><br />
可以看到，它提供了几个参数：输入了指令的玩家，指令字符串本身（不包括前面的斜杠 '/'）以及核心指令 createvehicle 以后的任意文本，本例中 "468" 为核心指令以后的文本，其为 Sanchez 交通工具的 ID。所有的指令处理器中，前两个参数都是一样且必须有的（参见 [[addEventHandler]] 文档）。因此，任意的指令处理器中，您都必须得要先定义这两个基本参数，再附加任意数量的附加参数。（附加参数有多少个，核心指令后的附加指令信息就有多少；本例中，createvehicle 有一个表示交通工具 ID 的附加指令信息，因此附加参数数量同为一个）<br />
<br />
"注意：必须要在定义了指令处理函数'''之后'''再创建指令处理器，否则指令处理器届时将无法找到其处理函数。"<br />
<br />
====编写函数====<br />
为了完成我们所创建的函数，我们得先想想我们要在该函数内完成的一些事：<br />
* 获取玩家位置以便知道在何处刷出交通工具（我们希望在玩家身边刷出）<br />
* 计算最理想的交通工具刷出点（我们不希望玩家会卡在车辆内）<br />
* 刷出交通工具<br />
* 检查交通工具是否成功刷出，如果没有则输出错误信息<br />
<br />
为了实现以上的需求，我们需要使用一些 API 函数。可以在[[Script Functions|服务端函数列表]]中找到我们所需的函数。首先我们需要一个用于取得玩家位置的函数。由于玩家属于 “元素” (Element)，我们找到 '''针对元素的 API 函数'''，并找到 [[getElementPosition]] 函数。单击该函数名便可阅读该函数的文档。文档内详细说明了函数的调用语法，返回值以及其示例代码。函数调用语法告诉我们在调用函数时应该提供什么参数。<br />
<br />
[[getElementPosition]] 的调用语法为：<br />
<syntaxhighlight lang="lua"><br />
float, float, float getElementPosition ( element theElement )<br />
</syntaxhighlight><br />
<br />
函数名前的三个 "float" 表示的是返回值类型。本例中表示该函数返回三个浮点数（x、y 及 z）。括号内，可以看到调用该函数时所需提供的参数。本例中只需要传递一个表示欲获取其位置的元素，在这里即玩家。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- 获取玩家位置并将信息放入 x、y 及 z 变量中<br />
-- （local 的意思是定义一个局部变量，在其作用域以外的地方无法访问，本例中即函数作用域）<br />
local x,y,z = getElementPosition(thePlayer)<br />
end<br />
</syntaxhighlight><br />
<br />
下一步，我们希望确保交通工具不会直接刷在玩家所在的位置（这样会玩家卡在车辆内），因此我们把 "x" 变量的值增加了少许，让车辆在距离玩家更东的位置被刷出。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- 获取玩家位置<br />
x = x + 5 -- x 坐标增加 5 个单位<br />
end<br />
</syntaxhighlight><br />
<br />
现在我们需要另一个用于刷出车辆的函数。再次打开 [[Scripting Functions|服务端函数列表]]，这次因为要找的是和交通工具有关的，所以定位到 '''交通工具函数'''，并阅读 [[createVehicle]] 的文档。根据该函数的调用语法，该函数只有一个返回类型（最常见的情况），表示的是创建了的交通工具元素。同样，我们可以看到在调用语法中有一些用方括号 [ ] 括起来的参数，这类参数说明它们是可选的，调用时可以不提供。<br />
<br />
在我们所定义的函数中，一切需要传递给 [[createVehicle]] 函数的参数都准备好了：计算好的 "x, y, z" 变量以及通过玩家输入的游戏指令 "createvehicle 468" 所得到的交通工具 ID，可以通过 ''vehicleModel'' 参数得到该 ID。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- 获取玩家位置<br />
x = x + 5 -- x 坐标增加 5 个单位<br />
-- 创建交通工具并将返回值存入到 ''createdVehicle'' 变量内<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
end<br />
</syntaxhighlight><br />
<br />
当然这些代码还有改善的余地，但至少我们还可以添加一个用于检测交通工具是否成功创建的代码。阅读 [[createVehicle]] 函数文档的 '''返回值''' 部分，该部分说明：若该函数返回 ''false''，则说明交通工具创建失败。因此，我们需要检查 ''createVehicle'' 变量的值以检测交通工具是否创建成功。<br />
<br />
以下是完整的脚本代码：<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- 获取玩家位置<br />
x = x + 5 -- x 坐标增加 5 个单位<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
-- 检查返回值是否为 ''false''<br />
if (createdVehicle == false) then<br />
-- 如果是，将错误信息发送给该特定玩家<br />
outputChatBox("Failed to create vehicle.",thePlayer)<br />
end<br />
end<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
<br />
上例代码中，还介绍了另一个用于发送客户端信息的 [[outputChatBox]] 函数。现在，您应该有能力可以自行阅读 API 函数文档了。若需要进一步学习高级脚本编写，请阅读[[Map manager|地图管理器]]教程。<br />
<br />
==必知==<br />
目前为止，您已经接触到及知悉了有关资源、指令处理器及如何在文档中寻找 API 函数，但要学的还有很多。本节将粗略告诉您有关这些学习内容，您可以自行阅读相关教程。<br />
===客户端及服务端脚本===<br />
您可能曾经了解或是看到过所谓 “客户端及服务端脚本” (Server/Client Script) 的概念或名称了。事实上，您不仅能够编写典型的运行在服务器之上的，用于提供游戏指令处理等需求的脚本；还能够编写运行在 MTA 玩家客户端之上的脚本。之可以编写客户端脚本，原因是一些 MTA 所提供的特殊功能只能在客户端上执行（例如图形操作界面），或是在客户端上执行一些代码比在服务端上执行效率要高些。<br />
<br />
大部分您所制作的资源（游戏模式、地图）可能都是服务端脚本，例如本教程前面所介绍的脚本。但如果您所编写的代码无法在服务端上执行，则您可能需要令其可在客户端上运行（即编写客户端脚本）。若要开始尝试编写一个客户端脚本，您需要创建一个脚本文件（例如，把它命名为 ''client.lua''），并修改 meta.xml 如下：<br />
<syntaxhighlight lang="xml"><br />
<script src="client.lua" type="client" /><br />
</syntaxhighlight><br />
''type'' 属性默认值为 'server'（即默认服务端脚本），因此只有在需要指定其是客户端脚本时才显式指定 ''type'' 属性。一个脚本文件一旦其 ''type'' 属性的值设置为 ''client''，则玩家连接到服务器时，该脚本文件会自动下载到玩家客户端。有关更多信息，请阅读[[客户端脚本]]教程。<br />
<br />
===更复杂的资源===<br />
上一节简单介绍了如何添加一个客户端脚本，但其实您什么都可以做到。正如本教程开头提到过，资源可以是任何类型的游戏模块。这些资源本身做什么或提供什么功能，便决定了它们的类型是什么。首先我们来分析一下下面的这些资源：<br />
<br />
====第一一个示例资源 —— 辅助类资源====<br />
<syntaxhighlight lang="xml"><br />
/admin_commands<br />
/meta.xml<br />
/commands.lua<br />
/client.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="admin commands" /><br />
<script src="commands.lua" /><br />
<script src="client.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* ''commands.lua'' 提供一些管理员指令，例如封禁玩家、玩家禁言等<br />
* ''client.lua'' 提供图形操作界面以简化玩家操作<br />
<br />
该示例资源可以随时被使用（也可以设置为随服务器而自动启动），原因是该资源对于整个游戏流程而言有一定的帮助（管理服务器）且不会影响到正常的游戏过程。<br />
<br />
====第二个示例资源 —— 游戏模式====<br />
<syntaxhighlight lang="xml"><br />
/counterstrike<br />
/meta.xml<br />
/counterstrike.lua<br />
/buymenu.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike remake" type="gamemode" /><br />
<script src="counterstrike.lua" /><br />
<script src="buymenu.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* ''counterstrike.lua'' 包含有类似于以下功能的实现：<br />
** 允许玩家选择其团队并刷出玩家<br />
** 把武器、目标及游戏指示提供给玩家<br />
** 规定游戏规则。例如：一盘游戏的时间、玩家死后会发生什么等<br />
** 等等等等...<br />
* ''buymenu.lua'' 是一个客户端脚本，其用于创建武器购买菜单（使用到了图形操作界面，因此必须写为客户端脚本）<br />
<br />
This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.<br />
<br />
This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.<br />
<br />
====Third example - A Map====<br />
<syntaxhighlight lang="xml"><br />
/cs-airport<br />
/meta.xml<br />
/airport.map<br />
/airport.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" /><br />
<map src="airport.map" /><br />
<script src="airport.lua" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:<br />
** Where the players should spawn, with what weapons, what teams there are<br />
** What the targets are<br />
** Weather, World Time, Timelimit<br />
** Provide vehicles<br />
* The ''airport.lua'' might contain map-specific features, that may include:<br />
** Opening some door/make something explode when something specific happens<br />
** Create or move some custom objects, or manipulate objects that are created through the .map file<br />
** .. anything else map-specific you can think of<br />
<br />
As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.<br />
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.<br />
<br />
The ''airport.map'' file might look similiar to this:<br />
<syntaxhighlight lang="xml"><br />
<map mode="deathmatch" version="1.0"><br />
<terrorists><br />
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" /><br />
</terrorists><br />
<counterterrorists><br />
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" /><br />
</counterterrorists><br />
<br />
<bomb posX="23342.23" posY="" posZ="" /><br />
<br />
<vehicle posX="" posY="" posZ="" model="602" /> <br />
<vehicle posX="" posY="" posZ="" model="603" /> <br />
</map><br />
</syntaxhighlight><br />
<br />
When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.<br />
<br />
===Events===<br />
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].<br />
<br />
This example will output a message with the name of the player who died:<br />
<syntaxhighlight lang="lua"><br />
function playerDied(totalAmmo, killer, killerWeapon, bodypart)<br />
outputChatBox(getPlayerName(source).." died!")<br />
end<br />
addEventHandler("onPlayerWasted",getRootElement(),playerDied)<br />
</syntaxhighlight><br />
<br />
Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.<br />
<br />
==Where to go from here==<br />
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.<br />
{{note|From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.}}<br />
'''See also:'''<br />
* [[Advanced Topics]]<br />
[[es:Introducción a la Programación]]<br />
[[it:Introduzione allo scripting]]<br />
[[nl:Scripting_introductie]]<br />
[[pt-br:Introdução ao Scripting]]<br />
[[ru:Scripting Introduction]]<br />
[[ar:مقدمه_في_البرمجه]]</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/%E8%84%9A%E6%9C%AC%E7%BC%96%E5%86%99%E4%BB%8B%E7%BB%8D&diff=37543ZH-CN/脚本编写介绍2013-11-11T11:16:57Z<p>JoeZhao: </p>
<hr />
<div>对于 MTA 服务器而言，“资源” (Resource) 是十分重要的一个概念。一个资源本身表现为一个包含了一系列文件的文件夹或压缩文件 (zip)，外包含一个用于指示服务器如何加载资源以及资源所包含文件说明的元数据文件 (Meta File)。可把资源的概念视作是运行在操作系统之上的程序 —— 它可以被启动或停止执行，且多个资源可以同时运行在服务器上。<br />
<br />
所谓脚本编程，本质上即是在编写资源。资源可以定义它自身的类型为游戏模式、地图等。MTA 自带一些可供您的游戏模式使用的可选辅助用资源；例如 maplimits，一个用于限制玩家行动范围的资源；或是 deathpickups，用于创建武器拾取物以供辅助死亡竞技 (Deathmatch) 游戏模式。<br />
{{Tip|您应该使用支持 Lua 格式代码的编辑器以编写脚本，以提高脚本编写的效率。我们建议使用 [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] 或 [http://luaedit.sourceforge.net/ LuaEdit]。我们也提供测试版的 [[MTASE|MTA 脚本编辑器]]（目前仍在开发中）。}}<br />
<br />
==创建一个脚本==<br />
第一步，我们将开始一步一步学习如何编写一个能让玩家到处行走的简单脚本。<br />
===脚本都在哪里存放着？===<br />
首先让我们来看看脚本的文件结构。打开 MTA 服务器目录，并定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/<br />
<br />
在该目录下，可以看到一系列 MTA 自带的示例脚本压缩文件。每个压缩文件都是一个 “资源”，在服务器启动时它们会被自动解压并被加载到服务器上运行。若需创建一个新资源，只需在该目录下新建一个任意名称的文件夹。在本教程中我们以 "myserver" 资源作为演示。<br />
<br />
现在请定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/myserver/<br />
<br />
===定义您的资源===<br />
为了能够让服务器得知资源内所包含的数据，每个资源内都必须包含一个位于资源根目录下的 "meta.xml" 文件（本例即 "myserver" 文件夹为资源根目录）。因此我们需要新建该文件，并以记事本方式打开。<br />
<br />
在 "meta.xml" 文件内输入以下的代码：<br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" /><br />
<script src="script.lua" /><br />
</meta><br />
</syntaxhighlight><br />
在 "<info />" 标签中，有一个用于指定资源类型的 "type" 属性。以上代码中指定了该资源类型为 "gamemode"（游戏模式），其他可选的资源类型还有常规包含文件或 "map"（地图），后文将会详细解释。目前只需要知道游戏模式是所有服务器的必不可少的核心，任意服务器都必须要有一个游戏模式。<br />
<br />
"<script />" 标签指明了该资源内所包含的脚本文件，后文将会详细解释。<br />
===创建一个简单的脚本===<br />
注意上例代码中的 "<script />" 标签中并没有将 .lua 文件指定在其他目录路径下，因此现在需要创建一个与 meta.xml 文件同目录下的 .lua 脚本文件；随后，请把以下代码复制到新创建的 script.lua 文件中：<br />
<syntaxhighlight lang="lua"><br />
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10<br />
function joinHandler()<br />
spawnPlayer(source, spawnX, spawnY, spawnZ)<br />
fadeCamera(source, true)<br />
setCameraTarget(source, source)<br />
outputChatBox("Welcome to My Server", source)<br />
end<br />
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)<br />
</syntaxhighlight><br />
当玩家进入服务器后，脚本会将玩家刷到上例代码所指定的出生点坐标 (x, y, z)。注意必须要使用 "fadeCamera" 函数以避免屏幕全黑的情况；同样，DP2 以后的 MTA 版本中，也同样需要使用 "setCameraTarget" 函数以设置玩家摄像机的目标，否则玩家进入服务器后只会见到游戏内蓝色的天空。<br />
<br />
'''source''' 变量表示的是事件的触发者。由于以上代码会在玩家进入服务器时被触发，因此您需要使用该变量以确定是哪位玩家进入了服务器。因此上例代码只会影响到新进入了服务器的玩家，而非服务器内的所有玩家。<br />
<br />
上例代码中，我们可以看到一个 [[addEventHandler]] 函数；从中可看见 3 个参数：'onPlayerJoin'，其表明何时代码会被触发；getRootElement()，其表明了可能的事件触发者（getRootElement() 表示的是游戏内的一切事物或玩家，因此该事件可能是由游戏内的任意事物或玩家所触发的）。以及 joinHandler，其表明哪个函数在该事件 ('onPlayerJoin') 触发后会被执行。其他的代码细节会在后文中详细介绍，现在就启动服务器然后测试一下代码效果吧！<br />
<br />
===执行脚本===<br />
只需要执行 server/ 目录下的可执行文件即可启动服务器。启动服务器后，首先可以从服务器后台上看到一系列的服务器基本信息；注意 port number（端口数）信息，在进入服务器前需要使用到该信息。随后服务器会加载所有位于 mods/deathmatch/resources 目录下的资源，最后会看到提示 "ready to accept connections!"，即表明服务器启动成功。<br />
<br />
在玩家进入服务器前，必须要首先加载游戏模式。在服务器后台输入指令 "start myserver" 并按下回车键发送指令。服务器便会立即启动您刚刚所创建的游戏模式，并列出该游戏模式内所有的脚本代码性错误及警告提示。现在可以启动 MTA 客户端，点击 "Quick Connect" 并输入您在服务器后台上所看到的服务器 IP 地址及端口数。如果没有错误，几秒过后玩家就会出生在 Los Santos。<br />
<br />
接下来，我们将会在脚本中添加一条用于在玩家附近刷出交通工具的游戏指令。您可以跳过本章节并阅读更为高级的[[Map manager|地图管理器]]教程；您也可以阅读[[图形操作界面 (GUI) 脚本编写介绍]]教程以学习如何在 MTA 下创建图形操作界面 (GUI) 及对其进行脚本编写。<br />
<br />
==创建一个简单的游戏指令==<br />
打开先前我们所创建的 "script.lua" 文件。上文提到，我们需要创建一个可在玩家附近刷出交通工具的游戏指令。首先我们需要定义一个用于处理玩家输入指令的函数，以及一个用于创建玩家可从客户端控制台输入游戏指令的指令处理器。<br />
<br />
<syntaxhighlight lang="lua"><br />
-- 定义一个由指令处理器所调用的函数，并提供三个参数：thePlayer, command, vehicleModel<br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- 创建交通工具的代码<br />
end<br />
<br />
-- 创建一个指令处理器<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
"提示：您可以点击示例代码中的函数名以查看该 API 函数的文档。"<br />
<br />
====有关指令处理器====<br />
[[addCommandHandler]] 的第一个参数表明了玩家可以从客户端输入的游戏指令（同时也表明新建了这个游戏指令）；第二个参数是该游戏指令发送到服务端后所调用的函数，本例中该函数名为 "createVehicleForPlayer"。<br />
<br />
如果您有一定的编程经验，您应当知道调用函数的方法是这样的：<br />
<syntaxhighlight lang="lua"><br />
functionName(参数1, 参数2, 参数3, ..)<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
functionName(thePlayer, commandName, argument3, ..)<br />
</syntaxhighlight><br />
看看上例代码，我们发现参数1 为 thePlayer，参数2 为 commandName。thePlayer 表明哪位玩家发送了该游戏指令；而 commandName 表明游戏指令字符串。因此如果玩家发送了指令 "/greet"，commandName 便是 "greet"（不包含指令前面的斜杠 "/")。参数3 是玩家额外的输入，后文中将会提到。<br />
请记住前两个参数（thePlayer 及 commandName）是必不可少的参数，但是您可以随意命名这些参数以符合您的代码风格。<br />
<br />
We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.<br />
我们已经调用了 [[addCommandHandler]] 函数<br />
<br />
For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:<br />
例如：某玩家输入了游戏指令 "createvehicle 468" 以刷出 Sanchez，指令处理器随后会调用 createVehicleForPlayer 函数，然后我们看看这个 createVehicleForPlayer 函数是如何被调用的：<br />
<syntaxhighlight lang="lua"><br />
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer 表示的是输入了 createvehicle 指令的玩家<br />
</syntaxhighlight><br />
可以看到，它提供了几个参数：输入了指令的玩家，指令字符串本身（不包括前面的斜杠 '/'）以及核心指令 createvehicle 以后的任意文本，本例中 "468" 为核心指令以后的文本，其为 Sanchez 交通工具的 ID。所有的指令处理器中，前两个参数都是一样且必须有的（参见 [[addEventHandler]] 文档）。因此，任意的指令处理器中，您都必须得要先定义这两个基本参数，再附加任意数量的附加参数。（附加参数有多少个，核心指令后的附加指令信息就有多少；本例中，createvehicle 有一个表示交通工具 ID 的附加指令信息，因此附加参数数量同为一个）<br />
<br />
"注意：必须要在定义了指令处理函数'''之后'''再创建指令处理器，否则指令处理器届时将无法找到其处理函数。"<br />
<br />
====编写函数====<br />
为了完成我们所创建的函数，我们得先想想我们要在该函数内完成的一些事：<br />
* 获取玩家位置以便知道在何处刷出交通工具（我们希望在玩家身边刷出）<br />
* 计算最理想的交通工具刷出点（我们不希望玩家会卡在车辆内）<br />
* 刷出交通工具<br />
* 检查交通工具是否成功刷出，如果没有则输出错误信息<br />
<br />
为了实现以上的需求，我们需要使用一些 API 函数。可以在[[Script Functions|服务端函数列表]]中找到我们所需的函数。首先我们需要一个用于取得玩家位置的函数。由于玩家属于 “元素” (Element)，我们找到 '''针对元素的 API 函数'''，并找到 [[getElementPosition]] 函数。单击该函数名便可阅读该函数的文档。文档内详细说明了函数的调用语法，返回值以及其示例代码。函数调用语法告诉我们在调用函数时应该提供什么参数。<br />
<br />
[[getElementPosition]] 的调用语法为：<br />
<syntaxhighlight lang="lua"><br />
float, float, float getElementPosition ( element theElement )<br />
</syntaxhighlight><br />
<br />
函数名前的三个 "float" 表示的是返回值类型。本例中表示该函数返回三个浮点数（x、y 及 z）。括号内，可以看到调用该函数时所需提供的参数。本例中只需要传递一个表示欲获取其位置的元素，在这里即玩家。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- 获取玩家位置并将信息放入 x、y 及 z 变量中<br />
-- （local 的意思是定义一个局部变量，在其作用域以外的地方无法访问，本例中即函数作用域）<br />
local x,y,z = getElementPosition(thePlayer)<br />
end<br />
</syntaxhighlight><br />
<br />
下一步，我们希望确保交通工具不会直接刷在玩家所在的位置（这样会玩家卡在车辆内），因此我们把 "x" 变量的值增加了少许，让车辆在距离玩家更东的位置被刷出。<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- 获取玩家位置<br />
x = x + 5 -- x 坐标增加 5 个单位<br />
end<br />
</syntaxhighlight><br />
<br />
Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.<br />
<br />
We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
end<br />
</syntaxhighlight><br />
<br />
Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.<br />
<br />
Now we have our complete script:<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
-- check if the return value was ''false''<br />
if (createdVehicle == false) then<br />
-- if so, output a message to the chatbox, but only to this player.<br />
outputChatBox("Failed to create vehicle.",thePlayer)<br />
end<br />
end<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
<br />
As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].<br />
<br />
==What you need to know==<br />
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.<br />
===Clientside and Serverside scripts===<br />
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.<br />
<br />
Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:<br />
<syntaxhighlight lang="xml"><br />
<script src="client.lua" type="client" /><br />
</syntaxhighlight><br />
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].<br />
<br />
===More complex resources===<br />
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:<br />
<br />
====First example - A utility script====<br />
<syntaxhighlight lang="xml"><br />
/admin_commands<br />
/meta.xml<br />
/commands.lua<br />
/client.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="admin commands" /><br />
<script src="commands.lua" /><br />
<script src="client.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server<br />
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily<br />
<br />
This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.<br />
<br />
====Second example - A gamemode====<br />
<syntaxhighlight lang="xml"><br />
/counterstrike<br />
/meta.xml<br />
/counterstrike.lua<br />
/buymenu.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike remake" type="gamemode" /><br />
<script src="counterstrike.lua" /><br />
<script src="buymenu.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''counterstrike.lua'' contains similiar to the following features:<br />
** Let players choose their team and spawn them<br />
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)<br />
** Define the game's rules, e.g. when does the round end, what happens when a player dies<br />
** .. and maybe some more<br />
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons<br />
<br />
This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.<br />
<br />
This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.<br />
<br />
====Third example - A Map====<br />
<syntaxhighlight lang="xml"><br />
/cs-airport<br />
/meta.xml<br />
/airport.map<br />
/airport.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" /><br />
<map src="airport.map" /><br />
<script src="airport.lua" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:<br />
** Where the players should spawn, with what weapons, what teams there are<br />
** What the targets are<br />
** Weather, World Time, Timelimit<br />
** Provide vehicles<br />
* The ''airport.lua'' might contain map-specific features, that may include:<br />
** Opening some door/make something explode when something specific happens<br />
** Create or move some custom objects, or manipulate objects that are created through the .map file<br />
** .. anything else map-specific you can think of<br />
<br />
As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.<br />
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.<br />
<br />
The ''airport.map'' file might look similiar to this:<br />
<syntaxhighlight lang="xml"><br />
<map mode="deathmatch" version="1.0"><br />
<terrorists><br />
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" /><br />
</terrorists><br />
<counterterrorists><br />
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" /><br />
</counterterrorists><br />
<br />
<bomb posX="23342.23" posY="" posZ="" /><br />
<br />
<vehicle posX="" posY="" posZ="" model="602" /> <br />
<vehicle posX="" posY="" posZ="" model="603" /> <br />
</map><br />
</syntaxhighlight><br />
<br />
When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.<br />
<br />
===Events===<br />
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].<br />
<br />
This example will output a message with the name of the player who died:<br />
<syntaxhighlight lang="lua"><br />
function playerDied(totalAmmo, killer, killerWeapon, bodypart)<br />
outputChatBox(getPlayerName(source).." died!")<br />
end<br />
addEventHandler("onPlayerWasted",getRootElement(),playerDied)<br />
</syntaxhighlight><br />
<br />
Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.<br />
<br />
==Where to go from here==<br />
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.<br />
{{note|From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.}}<br />
'''See also:'''<br />
* [[Advanced Topics]]<br />
[[es:Introducción a la Programación]]<br />
[[it:Introduzione allo scripting]]<br />
[[nl:Scripting_introductie]]<br />
[[pt-br:Introdução ao Scripting]]<br />
[[ru:Scripting Introduction]]<br />
[[ar:مقدمه_في_البرمجه]]</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/%E8%84%9A%E6%9C%AC%E7%BC%96%E5%86%99%E4%BB%8B%E7%BB%8D&diff=37542ZH-CN/脚本编写介绍2013-11-11T10:34:10Z<p>JoeZhao: </p>
<hr />
<div>对于 MTA 服务器而言，“资源” (Resource) 是十分重要的一个概念。一个资源本身表现为一个包含了一系列文件的文件夹或压缩文件 (zip)，外包含一个用于指示服务器如何加载资源以及资源所包含文件说明的元数据文件 (Meta File)。可把资源的概念视作是运行在操作系统之上的程序 —— 它可以被启动或停止执行，且多个资源可以同时运行在服务器上。<br />
<br />
所谓脚本编程，本质上即是在编写资源。资源可以定义它自身的类型为游戏模式、地图等。MTA 自带一些可供您的游戏模式使用的可选辅助用资源；例如 maplimits，一个用于限制玩家行动范围的资源；或是 deathpickups，用于创建武器拾取物以供辅助死亡竞技 (Deathmatch) 游戏模式。<br />
{{Tip|您应该使用支持 Lua 格式代码的编辑器以编写脚本，以提高脚本编写的效率。我们建议使用 [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] 或 [http://luaedit.sourceforge.net/ LuaEdit]。我们也提供测试版的 [[MTASE|MTA 脚本编辑器]]（目前仍在开发中）。}}<br />
<br />
==创建一个脚本==<br />
第一步，我们将开始一步一步学习如何编写一个能让玩家到处行走的简单脚本。<br />
===脚本都在哪里存放着？===<br />
首先让我们来看看脚本的文件结构。打开 MTA 服务器目录，并定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/<br />
<br />
在该目录下，可以看到一系列 MTA 自带的示例脚本压缩文件。每个压缩文件都是一个 “资源”，在服务器启动时它们会被自动解压并被加载到服务器上运行。若需创建一个新资源，只需在该目录下新建一个任意名称的文件夹。在本教程中我们以 "myserver" 资源作为演示。<br />
<br />
现在请定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/myserver/<br />
<br />
===定义您的资源===<br />
为了能够让服务器得知资源内所包含的数据，每个资源内都必须包含一个位于资源根目录下的 "meta.xml" 文件（本例即 "myserver" 文件夹为资源根目录）。因此我们需要新建该文件，并以记事本方式打开。<br />
<br />
在 "meta.xml" 文件内输入以下的代码：<br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" /><br />
<script src="script.lua" /><br />
</meta><br />
</syntaxhighlight><br />
在 "<info />" 标签中，有一个用于指定资源类型的 "type" 属性。以上代码中指定了该资源类型为 "gamemode"（游戏模式），其他可选的资源类型还有常规包含文件或 "map"（地图），后文将会详细解释。目前只需要知道游戏模式是所有服务器的必不可少的核心，任意服务器都必须要有一个游戏模式。<br />
<br />
"<script />" 标签指明了该资源内所包含的脚本文件，后文将会详细解释。<br />
===创建一个简单的脚本===<br />
注意上例代码中的 "<script />" 标签中并没有将 .lua 文件指定在其他目录路径下，因此现在需要创建一个与 meta.xml 文件同目录下的 .lua 脚本文件；随后，请把以下代码复制到新创建的 script.lua 文件中：<br />
<syntaxhighlight lang="lua"><br />
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10<br />
function joinHandler()<br />
spawnPlayer(source, spawnX, spawnY, spawnZ)<br />
fadeCamera(source, true)<br />
setCameraTarget(source, source)<br />
outputChatBox("Welcome to My Server", source)<br />
end<br />
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)<br />
</syntaxhighlight><br />
当玩家进入服务器后，脚本会将玩家刷到上例代码所指定的出生点坐标 (x, y, z)。注意必须要使用 "fadeCamera" 函数以避免屏幕全黑的情况；同样，DP2 以后的 MTA 版本中，也同样需要使用 "setCameraTarget" 函数以设置玩家摄像机的目标，否则玩家进入服务器后只会见到游戏内蓝色的天空。<br />
<br />
'''source''' 变量表示的是事件的触发者。由于以上代码会在玩家进入服务器时被触发，因此您需要使用该变量以确定是哪位玩家进入了服务器。因此上例代码只会影响到新进入了服务器的玩家，而非服务器内的所有玩家。<br />
<br />
上例代码中，我们可以看到一个 [[addEventHandler]] 函数；从中可看见 3 个参数：'onPlayerJoin'，其表明何时代码会被触发；getRootElement()，其表明了可能的事件触发者（getRootElement() 表示的是游戏内的一切事物或玩家，因此该事件可能是由游戏内的任意事物或玩家所触发的）。以及 joinHandler，其表明哪个函数在该事件 ('onPlayerJoin') 触发后会被执行。其他的代码细节会在后文中详细介绍，现在就启动服务器然后测试一下代码效果吧！<br />
<br />
===执行脚本===<br />
只需要执行 server/ 目录下的可执行文件即可启动服务器。启动服务器后，首先可以从服务器后台上看到一系列的服务器基本信息；注意 port number（端口数）信息，在进入服务器前需要使用到该信息。随后服务器会加载所有位于 mods/deathmatch/resources 目录下的资源，最后会看到提示 "ready to accept connections!"，即表明服务器启动成功。<br />
<br />
在玩家进入服务器前，必须要首先加载游戏模式。在服务器后台输入指令 "start myserver" 并按下回车键发送指令。服务器便会立即启动您刚刚所创建的游戏模式，并列出该游戏模式内所有的脚本代码性错误及警告提示。现在可以启动 MTA 客户端，点击 "Quick Connect" 并输入您在服务器后台上所看到的服务器 IP 地址及端口数。如果没有错误，几秒过后玩家就会出生在 Los Santos。<br />
<br />
接下来，我们将会在脚本中添加一条用于在玩家附近刷出交通工具的游戏指令。您可以跳过本章节并阅读更为高级的[[Map manager|地图管理器]]教程；您也可以阅读[[图形操作界面 (GUI) 脚本编写介绍]]教程以学习如何在 MTA 下创建图形操作界面 (GUI) 及对其进行脚本编写。<br />
<br />
==Creating a simple command==<br />
==创建一个简单的游戏指令==<br />
打开先前我们所创建的 "script.lua" 文件。上文提到，我们需要创建一个可在玩家附近刷出交通工具的游戏指令。首先我们需要定义一个用于处理玩家输入指令的函数，以及一个用于创建玩家可从客户端控制台输入游戏指令的指令处理器。<br />
<br />
<syntaxhighlight lang="lua"><br />
-- 定义一个由指令处理器所调用的函数，并提供三个参数：thePlayer, command, vehicleModel<br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- 创建交通工具的代码<br />
end<br />
<br />
-- 创建一个指令处理器<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
"提示：您可以点击示例代码中的函数名以查看该 API 函数的文档。"<br />
<br />
====有关指令处理器====<br />
[[addCommandHandler]] 的第一个参数表明了玩家可以从客户端输入的游戏指令（同时也表明新建了这个游戏指令）；第二个参数是该游戏指令发送到服务端后所调用的函数，本例中该函数名为 "createVehicleForPlayer"。<br />
<br />
如果您有一定的编程经验，您应当知道调用函数的方法是这样的：<br />
<syntaxhighlight lang="lua"><br />
functionName(参数1, 参数2, 参数3, ..)<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
functionName(thePlayer, commandName, argument3, ..)<br />
</syntaxhighlight><br />
看看上例代码，我们发现参数1 为 thePlayer，参数2 为 commandName。thePlayer 表明哪位玩家发送了该游戏指令；而 commandName 表明游戏指令字符串。因此如果玩家发送了指令 "/greet"，commandName 便是 "greet"（不包含指令前面的斜杠 "/")。参数3 是玩家额外的输入，后文中将会提到。<br />
请记住前两个参数（thePlayer 及 commandName）是必不可少的参数，但是您可以随意命名这些参数以符合您的代码风格。<br />
<br />
We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.<br />
我们已经调用了 [[addCommandHandler]] 函数<br />
<br />
For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:<br />
例如：某玩家输入了游戏指令 "createvehicle 468" 以刷出 Sanchez，指令处理器随后会调用 createVehicleForPlayer 函数，然后我们看看这个 createVehicleForPlayer 函数是如何被调用的：<br />
<syntaxhighlight lang="lua"><br />
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer 表示的是输入了 createvehicle 指令的玩家<br />
</syntaxhighlight><br />
可以看到，它提供了几个参数：输入了指令的玩家，指令字符串本身（不包括前面的斜杠 '/'）以及核心指令 createvehicle 以后的任意文本，本例中 "468" 为核心指令以后的文本，其为 Sanchez 交通工具的 ID。所有的指令处理器中，前两个参数都是一样且必须有的（参见 [[addEventHandler]] 文档）。因此，任意的指令处理器中，您都必须得要先定义这两个基本参数，再附加任意数量的附加参数。（附加参数有多少个，核心指令后的附加指令信息就有多少；本例中，createvehicle 有一个表示交通工具 ID 的附加指令信息，因此附加参数数量同为一个）<br />
<br />
"注意：必须要在定义了指令处理函数'''之后'''再创建指令处理器，否则指令处理器届时将无法找到其处理函数。"<br />
<br />
====编写函数====<br />
为了完成我们所创建的函数，我们得先想想我们要在该函数内完成的一些事：<br />
* 获取玩家位置以便知道在何处刷出交通工具（我们希望在玩家身边刷出）<br />
* 计算最理想的交通工具刷出点（我们不希望玩家会卡在车辆内）<br />
* 刷出交通工具<br />
* 检查交通工具是否成功刷出，如果没有则输出错误信息<br />
<br />
为了实现以上的需求，我们需要使用一些 API 函数。可以在[[Script Functions|服务端函数列表]]中找到我们所需的函数。首先我们需要一个用于取得玩家位置的函数。由于玩家属于 “元素” (Element)，我们找到 '''针对元素的 API 函数'''，并找到 [[getElementPosition]] 函数。单击该函数名便可阅读该函数的文档。文档内详细说明了函数的调用方法，返回值以及其示例代码。调用方法告诉我们在调用函数时应该提供什么参数。<br />
<br />
For [[getElementPosition]], the syntax is:<br />
<syntaxhighlight lang="lua"><br />
float, float, float getElementPosition ( element theElement )<br />
</syntaxhighlight><br />
<br />
The three ''float'' in front of the function name are the return type. In this case it means the function returns three floating point numbers. (x, y and z) Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- get the position and put it in the x,y,z variables<br />
-- (local means, the variables only exist in the current scope, in this case, the function)<br />
local x,y,z = getElementPosition(thePlayer)<br />
end<br />
</syntaxhighlight><br />
<br />
Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the ''x'' variable, which will make it spawn east from the player.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
end<br />
</syntaxhighlight><br />
<br />
Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.<br />
<br />
We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
end<br />
</syntaxhighlight><br />
<br />
Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.<br />
<br />
Now we have our complete script:<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
-- check if the return value was ''false''<br />
if (createdVehicle == false) then<br />
-- if so, output a message to the chatbox, but only to this player.<br />
outputChatBox("Failed to create vehicle.",thePlayer)<br />
end<br />
end<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
<br />
As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].<br />
<br />
==What you need to know==<br />
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.<br />
===Clientside and Serverside scripts===<br />
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.<br />
<br />
Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:<br />
<syntaxhighlight lang="xml"><br />
<script src="client.lua" type="client" /><br />
</syntaxhighlight><br />
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].<br />
<br />
===More complex resources===<br />
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:<br />
<br />
====First example - A utility script====<br />
<syntaxhighlight lang="xml"><br />
/admin_commands<br />
/meta.xml<br />
/commands.lua<br />
/client.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="admin commands" /><br />
<script src="commands.lua" /><br />
<script src="client.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server<br />
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily<br />
<br />
This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.<br />
<br />
====Second example - A gamemode====<br />
<syntaxhighlight lang="xml"><br />
/counterstrike<br />
/meta.xml<br />
/counterstrike.lua<br />
/buymenu.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike remake" type="gamemode" /><br />
<script src="counterstrike.lua" /><br />
<script src="buymenu.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''counterstrike.lua'' contains similiar to the following features:<br />
** Let players choose their team and spawn them<br />
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)<br />
** Define the game's rules, e.g. when does the round end, what happens when a player dies<br />
** .. and maybe some more<br />
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons<br />
<br />
This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.<br />
<br />
This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.<br />
<br />
====Third example - A Map====<br />
<syntaxhighlight lang="xml"><br />
/cs-airport<br />
/meta.xml<br />
/airport.map<br />
/airport.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" /><br />
<map src="airport.map" /><br />
<script src="airport.lua" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:<br />
** Where the players should spawn, with what weapons, what teams there are<br />
** What the targets are<br />
** Weather, World Time, Timelimit<br />
** Provide vehicles<br />
* The ''airport.lua'' might contain map-specific features, that may include:<br />
** Opening some door/make something explode when something specific happens<br />
** Create or move some custom objects, or manipulate objects that are created through the .map file<br />
** .. anything else map-specific you can think of<br />
<br />
As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.<br />
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.<br />
<br />
The ''airport.map'' file might look similiar to this:<br />
<syntaxhighlight lang="xml"><br />
<map mode="deathmatch" version="1.0"><br />
<terrorists><br />
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" /><br />
</terrorists><br />
<counterterrorists><br />
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" /><br />
</counterterrorists><br />
<br />
<bomb posX="23342.23" posY="" posZ="" /><br />
<br />
<vehicle posX="" posY="" posZ="" model="602" /> <br />
<vehicle posX="" posY="" posZ="" model="603" /> <br />
</map><br />
</syntaxhighlight><br />
<br />
When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.<br />
<br />
===Events===<br />
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].<br />
<br />
This example will output a message with the name of the player who died:<br />
<syntaxhighlight lang="lua"><br />
function playerDied(totalAmmo, killer, killerWeapon, bodypart)<br />
outputChatBox(getPlayerName(source).." died!")<br />
end<br />
addEventHandler("onPlayerWasted",getRootElement(),playerDied)<br />
</syntaxhighlight><br />
<br />
Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.<br />
<br />
==Where to go from here==<br />
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.<br />
{{note|From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.}}<br />
'''See also:'''<br />
* [[Advanced Topics]]<br />
[[es:Introducción a la Programación]]<br />
[[it:Introduzione allo scripting]]<br />
[[nl:Scripting_introductie]]<br />
[[pt-br:Introdução ao Scripting]]<br />
[[ru:Scripting Introduction]]<br />
[[ar:مقدمه_في_البرمجه]]</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/%E8%84%9A%E6%9C%AC%E7%BC%96%E5%86%99%E4%BB%8B%E7%BB%8D&diff=37541ZH-CN/脚本编写介绍2013-11-11T10:10:55Z<p>JoeZhao: </p>
<hr />
<div>对于 MTA 服务器而言，“资源” (Resource) 是十分重要的一个概念。一个资源本身表现为一个包含了一系列文件的文件夹或压缩文件 (zip)，外包含一个用于指示服务器如何加载资源以及资源所包含文件说明的元数据文件 (Meta File)。可把资源的概念视作是运行在操作系统之上的程序 —— 它可以被启动或停止执行，且多个资源可以同时运行在服务器上。<br />
<br />
所谓脚本编程，本质上即是在编写资源。资源可以定义它自身的类型为游戏模式、地图等。MTA 自带一些可供您的游戏模式使用的可选辅助用资源；例如 maplimits，一个用于限制玩家行动范围的资源；或是 deathpickups，用于创建武器拾取物以供辅助死亡竞技 (Deathmatch) 游戏模式。<br />
{{Tip|您应该使用支持 Lua 格式代码的编辑器以编写脚本，以提高脚本编写的效率。我们建议使用 [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] 或 [http://luaedit.sourceforge.net/ LuaEdit]。我们也提供测试版的 [[MTASE|MTA 脚本编辑器]]（目前仍在开发中）。}}<br />
<br />
==创建一个脚本==<br />
第一步，我们将开始一步一步学习如何编写一个能让玩家到处行走的简单脚本。<br />
===脚本都在哪里存放着？===<br />
首先让我们来看看脚本的文件结构。打开 MTA 服务器目录，并定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/<br />
<br />
在该目录下，可以看到一系列 MTA 自带的示例脚本压缩文件。每个压缩文件都是一个 “资源”，在服务器启动时它们会被自动解压并被加载到服务器上运行。若需创建一个新资源，只需在该目录下新建一个任意名称的文件夹。在本教程中我们以 "myserver" 资源作为演示。<br />
<br />
现在请定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/myserver/<br />
<br />
===定义您的资源===<br />
为了能够让服务器得知资源内所包含的数据，每个资源内都必须包含一个位于资源根目录下的 "meta.xml" 文件（本例即 "myserver" 文件夹为资源根目录）。因此我们需要新建该文件，并以记事本方式打开。<br />
<br />
在 "meta.xml" 文件内输入以下的代码：<br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" /><br />
<script src="script.lua" /><br />
</meta><br />
</syntaxhighlight><br />
在 "<info />" 标签中，有一个用于指定资源类型的 "type" 属性。以上代码中指定了该资源类型为 "gamemode"（游戏模式），其他可选的资源类型还有常规包含文件或 "map"（地图），后文将会详细解释。目前只需要知道游戏模式是所有服务器的必不可少的核心，任意服务器都必须要有一个游戏模式。<br />
<br />
"<script />" 标签指明了该资源内所包含的脚本文件，后文将会详细解释。<br />
===创建一个简单的脚本===<br />
注意上例代码中的 "<script />" 标签中并没有将 .lua 文件指定在其他目录路径下，因此现在需要创建一个与 meta.xml 文件同目录下的 .lua 脚本文件；随后，请把以下代码复制到新创建的 script.lua 文件中：<br />
<syntaxhighlight lang="lua"><br />
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10<br />
function joinHandler()<br />
spawnPlayer(source, spawnX, spawnY, spawnZ)<br />
fadeCamera(source, true)<br />
setCameraTarget(source, source)<br />
outputChatBox("Welcome to My Server", source)<br />
end<br />
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)<br />
</syntaxhighlight><br />
当玩家进入服务器后，脚本会将玩家刷到上例代码所指定的出生点坐标 (x, y, z)。注意必须要使用 "fadeCamera" 函数以避免屏幕全黑的情况；同样，DP2 以后的 MTA 版本中，也同样需要使用 "setCameraTarget" 函数以设置玩家摄像机的目标，否则玩家进入服务器后只会见到游戏内蓝色的天空。<br />
<br />
'''source''' 变量表示的是事件的触发者。由于以上代码会在玩家进入服务器时被触发，因此您需要使用该变量以确定是哪位玩家进入了服务器。因此上例代码只会影响到新进入了服务器的玩家，而非服务器内的所有玩家。<br />
<br />
上例代码中，我们可以看到一个 [[addEventHandler]] 函数；从中可看见 3 个参数：'onPlayerJoin'，其表明何时代码会被触发；getRootElement()，其表明了可能的事件触发者（getRootElement() 表示的是游戏内的一切事物或玩家，因此该事件可能是由游戏内的任意事物或玩家所触发的）。以及 joinHandler，其表明哪个函数在该事件 ('onPlayerJoin') 触发后会被执行。其他的代码细节会在后文中详细介绍，现在就启动服务器然后测试一下代码效果吧！<br />
<br />
===执行脚本===<br />
只需要执行 server/ 目录下的可执行文件即可启动服务器。启动服务器后，首先可以从服务器后台上看到一系列的服务器基本信息；注意 port number（端口数）信息，在进入服务器前需要使用到该信息。随后服务器会加载所有位于 mods/deathmatch/resources 目录下的资源，最后会看到提示 "ready to accept connections!"，即表明服务器启动成功。<br />
<br />
在玩家进入服务器前，必须要首先加载游戏模式。在服务器后台输入指令 "start myserver" 并按下回车键发送指令。服务器便会立即启动您刚刚所创建的游戏模式，并列出该游戏模式内所有的脚本代码性错误及警告提示。现在可以启动 MTA 客户端，点击 "Quick Connect" 并输入您在服务器后台上所看到的服务器 IP 地址及端口数。如果没有错误，几秒过后玩家就会出生在 Los Santos。<br />
<br />
接下来，我们将会在脚本中添加一条用于在玩家附近刷出交通工具的游戏指令。您可以跳过本章节并阅读更为高级的[[Map manager|地图管理器]]教程；您也可以阅读[[图形操作界面 (GUI) 脚本编写介绍]]教程以学习如何在 MTA 下创建图形操作界面 (GUI) 及对其进行脚本编写。<br />
<br />
==Creating a simple command==<br />
==创建一个简单的游戏指令==<br />
打开先前我们所创建的 "script.lua" 文件。上文提到，我们需要创建一个可在玩家附近刷出交通工具的游戏指令。首先我们需要定义一个用于处理玩家输入指令的函数，以及一个用于创建玩家可从客户端控制台输入游戏指令的指令处理器。<br />
<br />
<syntaxhighlight lang="lua"><br />
-- 定义一个由指令处理器所调用的函数，并提供三个参数：thePlayer, command, vehicleModel<br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- 创建交通工具的代码<br />
end<br />
<br />
-- 创建一个指令处理器<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
"提示：您可以点击示例代码中的函数名以查看该 API 函数的文档。"<br />
<br />
====有关指令处理器===<br />
[[addCommandHandler]] 的第一个参数表明了玩家可以从客户端输入的游戏指令（同时也表明新建了这个游戏指令）；第二个参数是该游戏指令发送到服务端后所调用的函数，本例中该函数名为 "createVehicleForPlayer"。<br />
<br />
如果您有一定的编程经验，您应当知道调用函数的方法是这样的：<br />
<syntaxhighlight lang="lua"><br />
functionName(参数1, 参数2, 参数3, ..)<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
functionName(thePlayer, commandName, argument3, ..)<br />
</syntaxhighlight><br />
看看上例代码，我们发现参数1 为 thePlayer，参数2 为 commandName。thePlayer 表明哪位玩家发送了该游戏指令；而 commandName 表明游戏指令字符串。因此如果玩家发送了指令 "/greet"，commandName 便是 "greet"（不包含指令前面的斜杠 "/")。参数3 是玩家额外的输入，后文中将会提到。<br />
请记住前两个参数（thePlayer 及 commandName）是必不可少的参数，但是您可以随意命名这些参数以符合您的代码风格。<br />
<br />
We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.<br />
<br />
<br />
For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:<br />
<syntaxhighlight lang="lua"><br />
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer is the player element of the player who entered the command<br />
</syntaxhighlight><br />
As we can see, it provides several parameters: the player who called the command, the command he entered and whatever text he had after that, in this case "468" as vehicle id for the Sanchez. The first two parameters are the same with all command handlers, which you can read on the [[addEventHandler]] page. For this fact, you always have to define at least those two parameters to use any after that (for example to process text that was entered after the command, like in our example the vehicle model id).<br />
<br />
''Note: You have to add the command handler AFTER you defined the handler function, else it can't find it. The order of execution matters.''<br />
<br />
====Writing the function====<br />
In order to fill the function we created, we need to think about what we have to do:<br />
* Get the players position, so we know where to spawn the vehicle (we want it to appear right beside the player)<br />
* Calculate the position we want to spawn the vehicle at (we don't want it to appear in the player)<br />
* Spawn the vehicle<br />
* Check if it has been spawned successfully, or output a message<br />
<br />
In order to achieve our goals, we have to use several functions. To find function we need to use, we should visit the [[Scripting Functions|Server Functions List]]. First we need a function to get the players position. Since players are Elements, we first jump to the '''Element functions''' where we find the [[getElementPosition]] function. By clicking on the function name in the list, you get to the function description. There we can see the syntax, what it returns and usually an example. The syntax shows us what arguments we can or have to submit.<br />
<br />
For [[getElementPosition]], the syntax is:<br />
<syntaxhighlight lang="lua"><br />
float, float, float getElementPosition ( element theElement )<br />
</syntaxhighlight><br />
<br />
The three ''float'' in front of the function name are the return type. In this case it means the function returns three floating point numbers. (x, y and z) Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- get the position and put it in the x,y,z variables<br />
-- (local means, the variables only exist in the current scope, in this case, the function)<br />
local x,y,z = getElementPosition(thePlayer)<br />
end<br />
</syntaxhighlight><br />
<br />
Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the ''x'' variable, which will make it spawn east from the player.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
end<br />
</syntaxhighlight><br />
<br />
Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.<br />
<br />
We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
end<br />
</syntaxhighlight><br />
<br />
Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.<br />
<br />
Now we have our complete script:<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
-- check if the return value was ''false''<br />
if (createdVehicle == false) then<br />
-- if so, output a message to the chatbox, but only to this player.<br />
outputChatBox("Failed to create vehicle.",thePlayer)<br />
end<br />
end<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
<br />
As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].<br />
<br />
==What you need to know==<br />
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.<br />
===Clientside and Serverside scripts===<br />
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.<br />
<br />
Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:<br />
<syntaxhighlight lang="xml"><br />
<script src="client.lua" type="client" /><br />
</syntaxhighlight><br />
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].<br />
<br />
===More complex resources===<br />
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:<br />
<br />
====First example - A utility script====<br />
<syntaxhighlight lang="xml"><br />
/admin_commands<br />
/meta.xml<br />
/commands.lua<br />
/client.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="admin commands" /><br />
<script src="commands.lua" /><br />
<script src="client.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server<br />
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily<br />
<br />
This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.<br />
<br />
====Second example - A gamemode====<br />
<syntaxhighlight lang="xml"><br />
/counterstrike<br />
/meta.xml<br />
/counterstrike.lua<br />
/buymenu.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike remake" type="gamemode" /><br />
<script src="counterstrike.lua" /><br />
<script src="buymenu.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''counterstrike.lua'' contains similiar to the following features:<br />
** Let players choose their team and spawn them<br />
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)<br />
** Define the game's rules, e.g. when does the round end, what happens when a player dies<br />
** .. and maybe some more<br />
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons<br />
<br />
This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.<br />
<br />
This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.<br />
<br />
====Third example - A Map====<br />
<syntaxhighlight lang="xml"><br />
/cs-airport<br />
/meta.xml<br />
/airport.map<br />
/airport.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" /><br />
<map src="airport.map" /><br />
<script src="airport.lua" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:<br />
** Where the players should spawn, with what weapons, what teams there are<br />
** What the targets are<br />
** Weather, World Time, Timelimit<br />
** Provide vehicles<br />
* The ''airport.lua'' might contain map-specific features, that may include:<br />
** Opening some door/make something explode when something specific happens<br />
** Create or move some custom objects, or manipulate objects that are created through the .map file<br />
** .. anything else map-specific you can think of<br />
<br />
As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.<br />
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.<br />
<br />
The ''airport.map'' file might look similiar to this:<br />
<syntaxhighlight lang="xml"><br />
<map mode="deathmatch" version="1.0"><br />
<terrorists><br />
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" /><br />
</terrorists><br />
<counterterrorists><br />
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" /><br />
</counterterrorists><br />
<br />
<bomb posX="23342.23" posY="" posZ="" /><br />
<br />
<vehicle posX="" posY="" posZ="" model="602" /> <br />
<vehicle posX="" posY="" posZ="" model="603" /> <br />
</map><br />
</syntaxhighlight><br />
<br />
When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.<br />
<br />
===Events===<br />
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].<br />
<br />
This example will output a message with the name of the player who died:<br />
<syntaxhighlight lang="lua"><br />
function playerDied(totalAmmo, killer, killerWeapon, bodypart)<br />
outputChatBox(getPlayerName(source).." died!")<br />
end<br />
addEventHandler("onPlayerWasted",getRootElement(),playerDied)<br />
</syntaxhighlight><br />
<br />
Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.<br />
<br />
==Where to go from here==<br />
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.<br />
{{note|From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.}}<br />
'''See also:'''<br />
* [[Advanced Topics]]<br />
[[es:Introducción a la Programación]]<br />
[[it:Introduzione allo scripting]]<br />
[[nl:Scripting_introductie]]<br />
[[pt-br:Introdução ao Scripting]]<br />
[[ru:Scripting Introduction]]<br />
[[ar:مقدمه_في_البرمجه]]</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/Main_Page&diff=37540ZH-CN/Main Page2013-11-11T10:05:29Z<p>JoeZhao: </p>
<hr />
<div>{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
<div style="/*border: 1px solid #D8D8D8;*/ padding-left: 15px; padding-right: 15px; height: 100%;"><br />
[[File:Mtalogo.png|left|100px|link=http://wiki.multitheftauto.com/]]'''欢迎来到 [[Multi Theft Auto]] Wiki。'''您可以在这里查询与 Multi Theft Auto 游戏及开发有关的任何相关信息。<br />
<br />
您可以'''创建地图及游戏模式'''；帮助我们'''编写脚本 API 文档'''、'''示例代码'''及'''教程'''；或是将'''游戏过程中所发现的 Bugs 告诉我们'''。<br />
<br />
如果您在编写脚本时遇到了问题，欢迎随时[[IRC Channel|联系我们]]。<br />
<br/><br/>[ 从此不再一个人玩 ]<br />
<br />
</div><br />
|}<br />
{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
|-<br />
|width="50%" style="vertical-align:top;" |<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px; background: #FFFCF2;"><br />
<div style="float:right; width: 32px;">[[File:Input-gaming.png|link=]]</div><br />
<h3>开始游戏</h3><br />
<div style="background: #FFEEAA; border: 1px solid #FFCD19;"><br />
[[File:Go-down.png|link=http://multitheftauto.googlecode.com/files/mtasa-1.3.4.exe/]] ''' [http://multitheftauto.googlecode.com/files/mtasa-1.3.4.exe/ 下载 Multi Theft Auto: San Andreas 1.3.4 ]'''</div><br />
* [[客户端手册]]<br />
* [[1.3.4 版本新特性]]<br />
* [[已知问题]]<br />
* [[从 MTA:Race 升级到 MTA:SA 1.3]]<br />
* [[服务端手册]]<br />
* [[地图管理器]]<br />
<br />
<h3>地图编辑器</h3><br />
*[[Resource:Editor|地图编辑器手册]]<br />
*[[Resource:Editor/EDF|编辑器定义格式 (EDF)]]<br />
*[[Resource:Editor/Plugins|插件]]<br />
*[[Resource:Editor#FAQ|常见问题解答]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Package-x-generic.png|link=]]</div><br />
<h3>数据库</h3><br />
本节介绍了有关 MTA 或其资源所提供的 Lua 兼容资源。<br />
* [[:Category:Resource|示例资源]] - 学习编写各类脚本的必经之路<br />
* [[客户端脚本]]<br />
* [[扩展模块]]<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Applications-development.png|link=]]</div><br />
<h3>二次开发 Multi Theft Auto</h3><br />
[[File:Go-down.png|link=http://nightly.mtasa.com/]] [http://nightly.mtasa.com/ Nightly builds]<br />
* [[Compiling_MTASA|在 Windows 平台上编译 MTASA]]<br />
* [[Building_MTASA_Server_on_Mac_OS_X|在 Mac OS X 平台上编译 MTA SA]]<br />
* [[Building_MTASA_Server_on_GNU_Linux|在 GNU/Linux 平台上编译 MTA SA]]<br />
* [http://wiki.multitheftauto.com/wiki/Coding_guidelines/ 二次开发指南]<br />
* [http://code.google.com/p/mtasa-blue Google Code SVN]<br />
* [[路线图]]<br />
* [http://bugs.mtasa.com/ Bug 追踪器]<br />
* [[开发分支]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Applications-office.png|link=]]</div><br />
<h3>Wiki - 您能够帮助我们</h3><br />
* 编写完全[[:Category:Incomplete|尚未完成的 API 文档]]。<br />
* [[:Category:Needs_Example |添加 API 及事件的使用示例代码]]。<br />
* 审查及核实[[:Category:Needs Checking|需要检查的页面]]。<br />
* 编写帮助新手的各类教程。<br />
* 将各 Wiki 页面翻译为您所使用的语言。<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Internet-group-chat.png|link=]]</div><br />
<h3>社区</h3><br />
* [http://forum.multitheftauto.com/ MTA 官方论坛]<br />
* IRC: [irc://irc.multitheftauto.com/mta irc.multitheftauto.com #mta]<br />
* [http://community.mtasa.com/ MTA Community] - 分享及资源下载。<br />
* [http://twitter.com/#!/MTAQA/ Twitter] - [http://www.youtube.com/user/MTAQA Youtube] - [http://plus.google.com/102014133442331779727/ Google+] - [http://www.moddb.com/mods/multi-theft-auto-san-andreas ModDB]<br />
</div><br />
<br />
| width="50%" style="vertical-align:top;" |<br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Accessories-text-editor.png|link=]]</div><br />
<h3>脚本编写</h3><br />
* [[ZH-CN/脚本编写介绍|脚本编写介绍]]<br />
* [[图形操作界面 (GUI) 脚本编写介绍]]<br />
* [[Debugging|脚本调试教程]] - 用以找出脚本中的错误<br />
* [[Resources|资源介绍]]<br />
** [[访问 Web 资源]] - 如何将资源信息写入网站中<br />
** [[:Category:Resource|示例资源]]<br />
** [[Meta.xml]] - 用于定义资源的描述文件<br />
** [[ACL]] - 访问控制列表 (Access Control List)，用于控制玩家及脚本的各类访问权限<br />
* [[Writing_Gamemodes|编写游戏模式]]<br />
* [[Useful_Functions|常用 API]]<br />
* [http://forum.mtasa.com/viewtopic.php?f=13&t=29363 离线 Wiki]<br />
<div style="float:right; width: 32px;">[[File:start-here.png|link=]]</div><br />
<h3>Lua</h3><br />
了解脚本编写所使用的语言 —— Lua。<br />
*[http://www.lua.org/pil/index.html Lua编程 手册]<br />
**[http://www.lua.org/manual/5.1/#index Lua函数参考]<br />
*[http://lua-users.org/wiki/TutorialDirectory Lua Wiki]<br />
*[http://nixstaller.berlios.de/manual/0.2/nixstaller_9.html 从Nixstaller到Lua的指南]<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px; background:#F2F2FF;"><br />
<div style="float:right; width: 32px;">[[File:Preferences-system.png|link=]]</div><br />
<h3>脚本编写参考</h3><br />
* [[Client Scripting Functions|客户端脚本 API]]<br />
* [[Client Scripting Events|客户端事件]]<br />
* [[Server Scripting Functions|服务端脚本 API]]<br />
* [[Server Scripting Events|服务端事件]]<br />
<!-- Incomplete * [[Module functions|服务器端外部模块的脚本功能列表]] --><br />
* [[MTA 类]] - 详细列明 MTA 中所有的自定义元素类型<br />
** [[Element|MTA 元素]] / [[元素树]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:System-file-manager.png|link=]]</div><br />
<h3>[[Id|ID 列表]]</h3><br />
*[[动作]]<br />
*[[任务皮肤]]<br />
*[[CJ衣服|服饰]]<br />
*[[车库|车库]]<br />
*[[室内控件]]<br />
*[[材质]]<br />
*[[弹射物体]]<br />
*[[雷达图标]]<br />
*[[声音及音效]]<br />
*[[交通工具]]<br />
*[[交通工具颜色]]<br />
*[[交通工具组件]]<br />
*[[车辆变体|交通工具改装组件]]<br />
*[[交通工具改装操纵]]<br />
*[[武器|武器]]<br />
*[[天气]]<br />
</div><br />
<div style="padding:4px 8px 8px 8px; margin:10px;"><br />
[[File:Osi symbol.png|75px|link=http://opensource.org/|left]]<br />
'''Multi Theft Auto''' 是'''一个开源项目'''。 <br />
<br/>任何人都可以为 MTA 作出更多的贡献！<br />
</div><br />
|-<br />
| colspan="2" |<br />
|}<br />
{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
<div style="padding-left: 15px; padding-right: 15px;" class="plainlinks"><br />
[[File:MTALogo_8ball.png|left|85px|link=Archive]]<br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''关于 [[Multi Theft Auto]]'''</li><br />
<li>[[档案]]</li><br />
<li>[[新闻报道]]</li><br />
<li>[http://code.google.com/p/mtasa-blue/people/list 开发者]</li><br />
</ul><br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''Multi Theft Auto 0.5'''</li><br />
<li>[[Archive#Multi_Theft_Auto_0.5|下载]]</li><br />
<li>[[MTA 0.5r2 Known Issues|已知问题]]</li><br />
</ul><br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''Wiki 统计'''</li><br />
<li>共 {{NUMBEROFARTICLES}} 篇文章</li><br />
<li>共 {{NUMBEROFPAGES}} 页页面</li><br />
<li>共 {{NUMBEROFUSERS}} 位注册用户</li><br />
</ul><br />
</div><br />
|}<br />
<br />
__NOTOC__<br />
__NOEDITSECTION__<br />
{{Languages list|en}}</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/%E8%84%9A%E6%9C%AC%E7%BC%96%E5%86%99%E4%BB%8B%E7%BB%8D&diff=37539ZH-CN/脚本编写介绍2013-11-11T09:52:31Z<p>JoeZhao: </p>
<hr />
<div>对于 MTA 服务器而言，“资源” (Resource) 是十分重要的一个概念。一个资源本身表现为一个包含了一系列文件的文件夹或压缩文件 (zip)，外包含一个用于指示服务器如何加载资源以及资源所包含文件说明的元数据文件 (Meta File)。可把资源的概念视作是运行在操作系统之上的程序 —— 它可以被启动或停止执行，且多个资源可以同时运行在服务器上。<br />
<br />
所谓脚本编程，本质上即是在编写资源。资源可以定义它自身的类型为游戏模式、地图等。MTA 自带一些可供您的游戏模式使用的可选辅助用资源；例如 maplimits，一个用于限制玩家行动范围的资源；或是 deathpickups，用于创建武器拾取物以供辅助死亡竞技 (Deathmatch) 游戏模式。<br />
{{Tip|您应该使用支持 Lua 格式代码的编辑器以编写脚本，以提高脚本编写的效率。我们建议使用 [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] 或 [http://luaedit.sourceforge.net/ LuaEdit]。我们也提供测试版的 [[MTASE|MTA 脚本编辑器]]（目前仍在开发中）。}}<br />
<br />
==创建一个脚本==<br />
第一步，我们将开始一步一步学习如何编写一个能让玩家到处行走的简单脚本。<br />
===脚本都在哪里存放着？===<br />
首先让我们来看看脚本的文件结构。打开 MTA 服务器目录，并定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/<br />
<br />
在该目录下，可以看到一系列 MTA 自带的示例脚本压缩文件。每个压缩文件都是一个 “资源”，在服务器启动时它们会被自动解压并被加载到服务器上运行。若需创建一个新资源，只需在该目录下新建一个任意名称的文件夹。在本教程中我们以 "myserver" 资源作为演示。<br />
<br />
现在请定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/myserver/<br />
<br />
===定义您的资源===<br />
为了能够让服务器得知资源内所包含的数据，每个资源内都必须包含一个位于资源根目录下的 "meta.xml" 文件（本例即 "myserver" 文件夹为资源根目录）。因此我们需要新建该文件，并以记事本方式打开。<br />
<br />
在 "meta.xml" 文件内输入以下的代码：<br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" /><br />
<script src="script.lua" /><br />
</meta><br />
</syntaxhighlight><br />
在 "<info />" 标签中，有一个用于指定资源类型的 "type" 属性。以上代码中指定了该资源类型为 "gamemode"（游戏模式），其他可选的资源类型还有常规包含文件或 "map"（地图），后文将会详细解释。目前只需要知道游戏模式是所有服务器的必不可少的核心，任意服务器都必须要有一个游戏模式。<br />
<br />
"<script />" 标签指明了该资源内所包含的脚本文件，后文将会详细解释。<br />
===创建一个简单的脚本===<br />
注意上例代码中的 "<script />" 标签中并没有将 .lua 文件指定在其他目录路径下，因此现在需要创建一个与 meta.xml 文件同目录下的 .lua 脚本文件；随后，请把以下代码复制到新创建的 script.lua 文件中：<br />
<syntaxhighlight lang="lua"><br />
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10<br />
function joinHandler()<br />
spawnPlayer(source, spawnX, spawnY, spawnZ)<br />
fadeCamera(source, true)<br />
setCameraTarget(source, source)<br />
outputChatBox("Welcome to My Server", source)<br />
end<br />
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)<br />
</syntaxhighlight><br />
当玩家进入服务器后，脚本会将玩家刷到上例代码所指定的出生点坐标 (x, y, z)。注意必须要使用 "fadeCamera" 函数以避免屏幕全黑的情况；同样，DP2 以后的 MTA 版本中，也同样需要使用 "setCameraTarget" 函数以设置玩家摄像机的目标，否则玩家进入服务器后只会见到游戏内蓝色的天空。<br />
<br />
'''source''' 变量表示的是事件的触发者。由于以上代码会在玩家进入服务器时被触发，因此您需要使用该变量以确定是哪位玩家进入了服务器。因此上例代码只会影响到新进入了服务器的玩家，而非服务器内的所有玩家。<br />
<br />
上例代码中，我们可以看到一个 [[addEventHandler]] 函数；从中可看见 3 个参数：'onPlayerJoin'，其表明何时代码会被触发；getRootElement()，其表明了可能的事件触发者（getRootElement() 表示的是游戏内的一切事物或玩家，因此该事件可能是由游戏内的任意事物或玩家所触发的）。以及 joinHandler，其表明哪个函数在该事件 ('onPlayerJoin') 触发后会被执行。其他的代码细节会在后文中详细介绍，现在就启动服务器然后测试一下代码效果吧！<br />
<br />
===执行脚本===<br />
只需要执行 server/ 目录下的可执行文件即可启动服务器。启动服务器后，首先可以从服务器后台上看到一系列的服务器基本信息；注意 port number（端口数）信息，在进入服务器前需要使用到该信息。随后服务器会加载所有位于 mods/deathmatch/resources 目录下的资源，最后会看到提示 "ready to accept connections!"，即表明服务器启动成功。<br />
<br />
在玩家进入服务器前，必须要首先加载游戏模式。在服务器后台输入指令 "start myserver" 并按下回车键发送指令。服务器便会立即启动您刚刚所创建的游戏模式，并列出该游戏模式内所有的脚本代码性错误及警告提示。现在可以启动 MTA 客户端，点击 "Quick Connect" 并输入您在服务器后台上所看到的服务器 IP 地址及端口数。如果没有错误，几秒过后玩家就会出生在 Los Santos。<br />
<br />
接下来，我们将会在脚本中添加一条用于在玩家附近刷出交通工具的游戏指令。您可以跳过本章节并阅读更为高级的[[Map manager|地图管理器]]教程；您也可以阅读[[图形操作界面 (GUI) 脚本编写介绍]]教程以学习如何在 MTA 下创建图形操作界面 (GUI) 及对其进行脚本编写。<br />
<br />
==Creating a simple command==<br />
Let's go back to the content of the ''script.lua'' file. As mentioned above, we want to provide a command to create a vehicle beside your current position in the game. Firstly we need to create a function we want to call and a command handler that creates the command the player will be able to enter in the console.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- create the function the command handler calls, with the arguments: thePlayer, command, vehicleModel<br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- create a vehicle and stuff<br />
end<br />
<br />
-- create a command handler<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
''Note: Function names are clickable in code examples on the wiki and linked to the functions' documentation.''<br />
<br />
====About command handlers====<br />
The first argument of [[addCommandHandler]] is the name of the command the player will be able to enter, the second argument is the function this will call, in this case ''createVehicleForPlayer''.<br />
<br />
If you have already experience in scripting, you will know that you call a function like this:<br />
<syntaxhighlight lang="lua"><br />
functionName(argument1, argument2, argument3, ..)<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
functionName(thePlayer, commandName, argument3, ..)<br />
</syntaxhighlight><br />
If we have a closer look on the lower example above, we can see argument1 is thePlayer and argument2 the commandName. thePlayer is simply the one who typed the command, so whatever you call it, the variable will contain the player who activated the command. commandName is simply the command they typed. So if they typed "/greet", this argument will contain "greet". Argument 3 is something extra the player typed, you'll learn it a little bit further in the tutorial. Never forget that the first 2 arguments are standard arguments, but you can name them to anything you want.<br />
<br />
We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.<br />
<br />
For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:<br />
<syntaxhighlight lang="lua"><br />
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer is the player element of the player who entered the command<br />
</syntaxhighlight><br />
As we can see, it provides several parameters: the player who called the command, the command he entered and whatever text he had after that, in this case "468" as vehicle id for the Sanchez. The first two parameters are the same with all command handlers, which you can read on the [[addEventHandler]] page. For this fact, you always have to define at least those two parameters to use any after that (for example to process text that was entered after the command, like in our example the vehicle model id).<br />
<br />
''Note: You have to add the command handler AFTER you defined the handler function, else it can't find it. The order of execution matters.''<br />
<br />
====Writing the function====<br />
In order to fill the function we created, we need to think about what we have to do:<br />
* Get the players position, so we know where to spawn the vehicle (we want it to appear right beside the player)<br />
* Calculate the position we want to spawn the vehicle at (we don't want it to appear in the player)<br />
* Spawn the vehicle<br />
* Check if it has been spawned successfully, or output a message<br />
<br />
In order to achieve our goals, we have to use several functions. To find function we need to use, we should visit the [[Scripting Functions|Server Functions List]]. First we need a function to get the players position. Since players are Elements, we first jump to the '''Element functions''' where we find the [[getElementPosition]] function. By clicking on the function name in the list, you get to the function description. There we can see the syntax, what it returns and usually an example. The syntax shows us what arguments we can or have to submit.<br />
<br />
For [[getElementPosition]], the syntax is:<br />
<syntaxhighlight lang="lua"><br />
float, float, float getElementPosition ( element theElement )<br />
</syntaxhighlight><br />
<br />
The three ''float'' in front of the function name are the return type. In this case it means the function returns three floating point numbers. (x, y and z) Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- get the position and put it in the x,y,z variables<br />
-- (local means, the variables only exist in the current scope, in this case, the function)<br />
local x,y,z = getElementPosition(thePlayer)<br />
end<br />
</syntaxhighlight><br />
<br />
Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the ''x'' variable, which will make it spawn east from the player.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
end<br />
</syntaxhighlight><br />
<br />
Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.<br />
<br />
We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
end<br />
</syntaxhighlight><br />
<br />
Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.<br />
<br />
Now we have our complete script:<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
-- check if the return value was ''false''<br />
if (createdVehicle == false) then<br />
-- if so, output a message to the chatbox, but only to this player.<br />
outputChatBox("Failed to create vehicle.",thePlayer)<br />
end<br />
end<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
<br />
As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].<br />
<br />
==What you need to know==<br />
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.<br />
===Clientside and Serverside scripts===<br />
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.<br />
<br />
Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:<br />
<syntaxhighlight lang="xml"><br />
<script src="client.lua" type="client" /><br />
</syntaxhighlight><br />
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].<br />
<br />
===More complex resources===<br />
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:<br />
<br />
====First example - A utility script====<br />
<syntaxhighlight lang="xml"><br />
/admin_commands<br />
/meta.xml<br />
/commands.lua<br />
/client.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="admin commands" /><br />
<script src="commands.lua" /><br />
<script src="client.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server<br />
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily<br />
<br />
This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.<br />
<br />
====Second example - A gamemode====<br />
<syntaxhighlight lang="xml"><br />
/counterstrike<br />
/meta.xml<br />
/counterstrike.lua<br />
/buymenu.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike remake" type="gamemode" /><br />
<script src="counterstrike.lua" /><br />
<script src="buymenu.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''counterstrike.lua'' contains similiar to the following features:<br />
** Let players choose their team and spawn them<br />
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)<br />
** Define the game's rules, e.g. when does the round end, what happens when a player dies<br />
** .. and maybe some more<br />
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons<br />
<br />
This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.<br />
<br />
This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.<br />
<br />
====Third example - A Map====<br />
<syntaxhighlight lang="xml"><br />
/cs-airport<br />
/meta.xml<br />
/airport.map<br />
/airport.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" /><br />
<map src="airport.map" /><br />
<script src="airport.lua" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:<br />
** Where the players should spawn, with what weapons, what teams there are<br />
** What the targets are<br />
** Weather, World Time, Timelimit<br />
** Provide vehicles<br />
* The ''airport.lua'' might contain map-specific features, that may include:<br />
** Opening some door/make something explode when something specific happens<br />
** Create or move some custom objects, or manipulate objects that are created through the .map file<br />
** .. anything else map-specific you can think of<br />
<br />
As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.<br />
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.<br />
<br />
The ''airport.map'' file might look similiar to this:<br />
<syntaxhighlight lang="xml"><br />
<map mode="deathmatch" version="1.0"><br />
<terrorists><br />
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" /><br />
</terrorists><br />
<counterterrorists><br />
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" /><br />
</counterterrorists><br />
<br />
<bomb posX="23342.23" posY="" posZ="" /><br />
<br />
<vehicle posX="" posY="" posZ="" model="602" /> <br />
<vehicle posX="" posY="" posZ="" model="603" /> <br />
</map><br />
</syntaxhighlight><br />
<br />
When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.<br />
<br />
===Events===<br />
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].<br />
<br />
This example will output a message with the name of the player who died:<br />
<syntaxhighlight lang="lua"><br />
function playerDied(totalAmmo, killer, killerWeapon, bodypart)<br />
outputChatBox(getPlayerName(source).." died!")<br />
end<br />
addEventHandler("onPlayerWasted",getRootElement(),playerDied)<br />
</syntaxhighlight><br />
<br />
Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.<br />
<br />
==Where to go from here==<br />
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.<br />
{{note|From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.}}<br />
'''See also:'''<br />
* [[Advanced Topics]]<br />
[[es:Introducción a la Programación]]<br />
[[it:Introduzione allo scripting]]<br />
[[nl:Scripting_introductie]]<br />
[[pt-br:Introdução ao Scripting]]<br />
[[ru:Scripting Introduction]]<br />
[[ar:مقدمه_في_البرمجه]]</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/%E8%84%9A%E6%9C%AC%E7%BC%96%E5%86%99%E4%BB%8B%E7%BB%8D&diff=37538ZH-CN/脚本编写介绍2013-11-11T09:33:28Z<p>JoeZhao: Created page with "对于 MTA 服务器而言，“资源” (Resource) 是十分重要的一个概念。一个资源本身表现为一个包含了一系列文件的文件夹或压缩文件 (zip)..."</p>
<hr />
<div>对于 MTA 服务器而言，“资源” (Resource) 是十分重要的一个概念。一个资源本身表现为一个包含了一系列文件的文件夹或压缩文件 (zip)，外包含一个用于指示服务器如何加载资源以及资源所包含文件说明的元数据文件 (Meta File)。可把资源的概念视作是运行在操作系统之上的程序 —— 它可以被启动或停止执行，且多个资源可以同时运行在服务器上。<br />
<br />
所谓脚本编程，本质上即是在编写资源。资源可以定义它自身的类型为游戏模式、地图等。MTA 自带一些可供您的游戏模式使用的可选辅助用资源；例如 maplimits，一个用于限制玩家行动范围的资源；或是 deathpickups，用于创建武器拾取物以供辅助死亡竞技 (Deathmatch) 游戏模式。<br />
{{提示|您应该使用支持 Lua 格式代码的编辑器以编写脚本，以提高脚本编写的效率。我们建议使用 [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] 或 [http://luaedit.sourceforge.net/ LuaEdit]。我们也提供测试版的 [[MTASE|MTA 脚本编辑器]]（目前仍在开发中）。}}<br />
<br />
==创建一个脚本==<br />
第一步，我们将开始一步一步学习如何编写一个能让玩家到处行走的简单脚本。<br />
===脚本都在哪里存放着？===<br />
首先让我们来看看脚本的文件结构。打开 MTA 服务器目录，并定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/<br />
<br />
在该目录下，可以看到一系列 MTA 自带的示例脚本压缩文件。每个压缩文件都是一个 “资源”，在服务器启动时它们会被自动解压并被加载到服务器上运行。若需创建一个新资源，只需在该目录下新建一个任意名称的文件夹。在本教程中我们以 "myserver" 资源作为演示。<br />
<br />
现在请定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/myserver/<br />
<br />
===定义您的资源===<br />
为了能够让服务器得知资源内所包含的数据，每个资源内都必须包含一个位于资源根目录下的 "meta.xml" 文件（本例即 "myserver" 文件夹为资源根目录）。因此我们需要新建该文件，并以记事本方式打开。<br />
<br />
在 "meta.xml" 文件内输入以下的代码：<br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" /><br />
<script src="script.lua" /><br />
</meta><br />
</syntaxhighlight><br />
在 "<info />" 标签中，有一个用于指定资源类型的 "type" 属性。以上代码中指定了该资源类型为 "gamemode"（游戏模式），其他可选的资源类型还有常规包含文件或 "map"（地图），后文将会详细解释。目前只需要知道游戏模式是所有服务器的必不可少的核心，任意服务器都必须要有一个游戏模式。<br />
<br />
"<script />" 标签指明了该资源内所包含的脚本文件，后文将会详细解释。<br />
===创建一个简单的脚本===<br />
注意上例代码中的 "<script />" 标签中并没有将 .lua 文件指定在其他目录路径下，因此现在需要创建一个与 meta.xml 文件同目录下的 .lua 脚本文件；随后，请把以下代码复制到新创建的 script.lua 文件中：<br />
<syntaxhighlight lang="lua"><br />
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10<br />
function joinHandler()<br />
spawnPlayer(source, spawnX, spawnY, spawnZ)<br />
fadeCamera(source, true)<br />
setCameraTarget(source, source)<br />
outputChatBox("Welcome to My Server", source)<br />
end<br />
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)<br />
</syntaxhighlight><br />
当玩家进入服务器后，脚本会将玩家刷到上例代码所指定的出生点坐标 (x, y, z)。注意必须要使用 "fadeCamera" 函数以避免屏幕全黑的情况；同样，DP2 以后的 MTA 版本中，也同样需要使用 "setCameraTarget" 函数以设置玩家摄像机的目标，否则玩家进入服务器后只会见到游戏内蓝色的天空。<br />
<br />
The '''source''' variable indicates who triggered the event. Since a player has joined when the code is triggered, you use this variable to look which has joined. So it'll spawn that player instead of everyone or a random person.<br />
<br />
If we have a closer look on [[addEventHandler]], you can see 3 things: 'onPlayerJoin', which indicates when it's triggered. getRootElement(), which shows by what/who it can be triggered. (getRootElement() is everything/everyone) And joinHandler, which indicates the function that has to be triggered after the event is triggered. Other details will be explained later in another example, now let's just run the server and try it out!<br />
<br />
===Running the script===<br />
To get the server started, simply run the executable under the server/ directory. A list of server stats will be shown first; note the port number, which you'll need when joining the game. Then the server loads all the resources under the mods/deathmatch/resources/ directory, and then "ready to accept connections!"<br />
<br />
Before you connect to the server, you must run the gamemode. Type "start myserver" and press Enter. The server will start the gamemode you just created, and will also show any errors and warnings from this point on. Now you can start the MTA client, and "Quick Connect" using the IP address of your server and the port number you saw earlier. If all goes well, after a few seconds your character will be walking on the streets of Los Santos.<br />
<br />
Next we'll add a command to your script that players can use to spawn a vehicle beside their position. You may skip it and check out more advanced scripting with the [[Map manager|Map Manager]], which continues this tutorial. Another branch from this tutorial is [[Introduction to Scripting GUI]], you may follow it to see how Graphical User Interface in MTA is drawn and scripted.<br />
<br />
==Creating a simple command==<br />
Let's go back to the content of the ''script.lua'' file. As mentioned above, we want to provide a command to create a vehicle beside your current position in the game. Firstly we need to create a function we want to call and a command handler that creates the command the player will be able to enter in the console.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- create the function the command handler calls, with the arguments: thePlayer, command, vehicleModel<br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- create a vehicle and stuff<br />
end<br />
<br />
-- create a command handler<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
''Note: Function names are clickable in code examples on the wiki and linked to the functions' documentation.''<br />
<br />
====About command handlers====<br />
The first argument of [[addCommandHandler]] is the name of the command the player will be able to enter, the second argument is the function this will call, in this case ''createVehicleForPlayer''.<br />
<br />
If you have already experience in scripting, you will know that you call a function like this:<br />
<syntaxhighlight lang="lua"><br />
functionName(argument1, argument2, argument3, ..)<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
functionName(thePlayer, commandName, argument3, ..)<br />
</syntaxhighlight><br />
If we have a closer look on the lower example above, we can see argument1 is thePlayer and argument2 the commandName. thePlayer is simply the one who typed the command, so whatever you call it, the variable will contain the player who activated the command. commandName is simply the command they typed. So if they typed "/greet", this argument will contain "greet". Argument 3 is something extra the player typed, you'll learn it a little bit further in the tutorial. Never forget that the first 2 arguments are standard arguments, but you can name them to anything you want.<br />
<br />
We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.<br />
<br />
For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:<br />
<syntaxhighlight lang="lua"><br />
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer is the player element of the player who entered the command<br />
</syntaxhighlight><br />
As we can see, it provides several parameters: the player who called the command, the command he entered and whatever text he had after that, in this case "468" as vehicle id for the Sanchez. The first two parameters are the same with all command handlers, which you can read on the [[addEventHandler]] page. For this fact, you always have to define at least those two parameters to use any after that (for example to process text that was entered after the command, like in our example the vehicle model id).<br />
<br />
''Note: You have to add the command handler AFTER you defined the handler function, else it can't find it. The order of execution matters.''<br />
<br />
====Writing the function====<br />
In order to fill the function we created, we need to think about what we have to do:<br />
* Get the players position, so we know where to spawn the vehicle (we want it to appear right beside the player)<br />
* Calculate the position we want to spawn the vehicle at (we don't want it to appear in the player)<br />
* Spawn the vehicle<br />
* Check if it has been spawned successfully, or output a message<br />
<br />
In order to achieve our goals, we have to use several functions. To find function we need to use, we should visit the [[Scripting Functions|Server Functions List]]. First we need a function to get the players position. Since players are Elements, we first jump to the '''Element functions''' where we find the [[getElementPosition]] function. By clicking on the function name in the list, you get to the function description. There we can see the syntax, what it returns and usually an example. The syntax shows us what arguments we can or have to submit.<br />
<br />
For [[getElementPosition]], the syntax is:<br />
<syntaxhighlight lang="lua"><br />
float, float, float getElementPosition ( element theElement )<br />
</syntaxhighlight><br />
<br />
The three ''float'' in front of the function name are the return type. In this case it means the function returns three floating point numbers. (x, y and z) Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- get the position and put it in the x,y,z variables<br />
-- (local means, the variables only exist in the current scope, in this case, the function)<br />
local x,y,z = getElementPosition(thePlayer)<br />
end<br />
</syntaxhighlight><br />
<br />
Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the ''x'' variable, which will make it spawn east from the player.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
end<br />
</syntaxhighlight><br />
<br />
Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.<br />
<br />
We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
end<br />
</syntaxhighlight><br />
<br />
Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.<br />
<br />
Now we have our complete script:<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
-- check if the return value was ''false''<br />
if (createdVehicle == false) then<br />
-- if so, output a message to the chatbox, but only to this player.<br />
outputChatBox("Failed to create vehicle.",thePlayer)<br />
end<br />
end<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
<br />
As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].<br />
<br />
==What you need to know==<br />
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.<br />
===Clientside and Serverside scripts===<br />
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.<br />
<br />
Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:<br />
<syntaxhighlight lang="xml"><br />
<script src="client.lua" type="client" /><br />
</syntaxhighlight><br />
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].<br />
<br />
===More complex resources===<br />
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:<br />
<br />
====First example - A utility script====<br />
<syntaxhighlight lang="xml"><br />
/admin_commands<br />
/meta.xml<br />
/commands.lua<br />
/client.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="admin commands" /><br />
<script src="commands.lua" /><br />
<script src="client.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server<br />
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily<br />
<br />
This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.<br />
<br />
====Second example - A gamemode====<br />
<syntaxhighlight lang="xml"><br />
/counterstrike<br />
/meta.xml<br />
/counterstrike.lua<br />
/buymenu.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike remake" type="gamemode" /><br />
<script src="counterstrike.lua" /><br />
<script src="buymenu.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''counterstrike.lua'' contains similiar to the following features:<br />
** Let players choose their team and spawn them<br />
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)<br />
** Define the game's rules, e.g. when does the round end, what happens when a player dies<br />
** .. and maybe some more<br />
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons<br />
<br />
This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.<br />
<br />
This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.<br />
<br />
====Third example - A Map====<br />
<syntaxhighlight lang="xml"><br />
/cs-airport<br />
/meta.xml<br />
/airport.map<br />
/airport.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" /><br />
<map src="airport.map" /><br />
<script src="airport.lua" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:<br />
** Where the players should spawn, with what weapons, what teams there are<br />
** What the targets are<br />
** Weather, World Time, Timelimit<br />
** Provide vehicles<br />
* The ''airport.lua'' might contain map-specific features, that may include:<br />
** Opening some door/make something explode when something specific happens<br />
** Create or move some custom objects, or manipulate objects that are created through the .map file<br />
** .. anything else map-specific you can think of<br />
<br />
As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.<br />
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.<br />
<br />
The ''airport.map'' file might look similiar to this:<br />
<syntaxhighlight lang="xml"><br />
<map mode="deathmatch" version="1.0"><br />
<terrorists><br />
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" /><br />
</terrorists><br />
<counterterrorists><br />
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" /><br />
</counterterrorists><br />
<br />
<bomb posX="23342.23" posY="" posZ="" /><br />
<br />
<vehicle posX="" posY="" posZ="" model="602" /> <br />
<vehicle posX="" posY="" posZ="" model="603" /> <br />
</map><br />
</syntaxhighlight><br />
<br />
When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.<br />
<br />
===Events===<br />
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].<br />
<br />
This example will output a message with the name of the player who died:<br />
<syntaxhighlight lang="lua"><br />
function playerDied(totalAmmo, killer, killerWeapon, bodypart)<br />
outputChatBox(getPlayerName(source).." died!")<br />
end<br />
addEventHandler("onPlayerWasted",getRootElement(),playerDied)<br />
</syntaxhighlight><br />
<br />
Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.<br />
<br />
==Where to go from here==<br />
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.<br />
{{note|From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.}}<br />
'''See also:'''<br />
* [[Advanced Topics]]<br />
[[es:Introducción a la Programación]]<br />
[[it:Introduzione allo scripting]]<br />
[[nl:Scripting_introductie]]<br />
[[pt-br:Introdução ao Scripting]]<br />
[[ru:Scripting Introduction]]<br />
[[ar:مقدمه_في_البرمجه]]</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/&diff=37537ZH-CN/2013-11-11T05:39:59Z<p>JoeZhao: Created page with "对于 MTA 服务器而言，资源是必不可少的。资源本身是一个包含了一系列文件的文件夹或是压缩 (zip) 文件，且包含一个用于指示服务器..."</p>
<hr />
<div>对于 MTA 服务器而言，资源是必不可少的。资源本身是一个包含了一系列文件的文件夹或是压缩 (zip) 文件，且包含一个用于指示服务器如何加载资源以及其所包含的文件的元数据文件。<br />
可以把资源视作是运行在操作系统上的程序 - 可以启动或停止资源，且多个资源可以同时运行。<br />
<br />
所谓脚本编写，即是在编写资源；资源具有自描述功能，即其可以说明自身是游戏模式或地图等等。MTA 也自带了一些可供您的游戏模式所使用的可选资源，例如用于限制玩家游戏范围的 maplimits 资源；或用于创建武器拾取物件的 deathpickups 资源。<br />
{{tip|您应使用任意支持 Lua 代码的编辑器以加快脚本编写效率。我们推荐您使用 [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] 或 [http://luaedit.sourceforge.net/ LuaEdit]。我们也提供非正式版本的 [[MTASE|MTA 脚本编辑器]]（目前仍在开发）。}}<br />
<br />
==创建脚本==<br />
第一步，我们来学习如何创建一个最简单的，可让玩家在城市内到处行走的脚本。<br />
===资源都在哪里？===<br />
首先，我们来看看脚本的文件结构。打开您的 MTA 服务器目录，并定位到以下路径：<br />
<br />
server/mods/deathmatch/resources/<br />
<br />
You will see a lot of .zip files, which are the packaged sample scripts shipped with MTA. Each file is a "resource", and they will all be unzipped and loaded by the server when it starts. To create your own resource, simply make a folder with your preferred name. We'll use "myserver" for this tutorial.<br />
您会看到在该目录下，有一系列的压缩文件 (.zip)，它们是 MTA 提供的示例脚本。每个文件都是一个“资源”；当服务器启动时，它们会被自动解压并加载到服务器中。<br />
若需要新建一个脚本，在该目录下新建一个任意取名的文件夹。本教程中我们以 "myserver" 文件夹作演示。<br />
<br />
现在您应该定位到了以下目录中：<br />
<br />
server/mods/deathmatch/resources/myserver/<br />
<br />
===定义您的资源===<br />
In order to let the server know what's in the resource, a ''meta.xml'' file must be created to list the resource's content. It must be located in the resource's root directory, which is the "myserver" folder in our case. So create a text file and name it "meta.xml", and open it with notepad.<br />
为了让服务器能够得知到资源内所包含的东西，必须要在资源文件夹的根目录（即 "myserver" 文件夹本身）内创建一个 ''meta.xml''。所以，我们新建一个 "meta.xml" 文件，然后以记事本方式打开它。<br />
<br />
Enter the following codes in the ''meta.xml'' file:<br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" /><br />
<script src="script.lua" /><br />
</meta><br />
</syntaxhighlight><br />
In the ''<info />'' tag, there's a "type" field which indicates that the resource is a ''gamemode'' instead of a regular include or a ''map'', which will be explained later. A gamemode is what you need to make a stand-alone server. <br />
<br />
The ''<script />'' tag indicates the script files contained in the resource, which we will create next.<br />
===Creating a simple script===<br />
Note that in the ''<script />'' tag above, the .lua file is not under another directory. Therefore we'll create the file in the same folder as meta.xml. Now you can copy and paste the following code into script.lua:<br />
<syntaxhighlight lang="lua"><br />
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10<br />
function joinHandler()<br />
spawnPlayer(source, spawnX, spawnY, spawnZ)<br />
fadeCamera(source, true)<br />
setCameraTarget(source, source)<br />
outputChatBox("Welcome to My Server", source)<br />
end<br />
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)<br />
</syntaxhighlight><br />
The script will spawn you at the coordinate (x, y, z) specified above, when you join the game. Note that the ''fadeCamera'' function must be used or the screen will be black. Also, in releases after DP2, you need to set the camera target (otherwise all the player will see is blue sky).<br />
<br />
The '''source''' variable indicates who triggered the event. Since a player has joined when the code is triggered, you use this variable to look which has joined. So it'll spawn that player instead of everyone or a random person.<br />
<br />
If we have a closer look on [[addEventHandler]], you can see 3 things: 'onPlayerJoin', which indicates when it's triggered. getRootElement(), which shows by what/who it can be triggered. (getRootElement() is everything/everyone) And joinHandler, which indicates the function that has to be triggered after the event is triggered. Other details will be explained later in another example, now let's just run the server and try it out!<br />
<br />
===Running the script===<br />
To get the server started, simply run the executable under the server/ directory. A list of server stats will be shown first; note the port number, which you'll need when joining the game. Then the server loads all the resources under the mods/deathmatch/resources/ directory, and then "ready to accept connections!"<br />
<br />
Before you connect to the server, you must run the gamemode. Type "start myserver" and press Enter. The server will start the gamemode you just created, and will also show any errors and warnings from this point on. Now you can start the MTA client, and "Quick Connect" using the IP address of your server and the port number you saw earlier. If all goes well, after a few seconds your character will be walking on the streets of Los Santos.<br />
<br />
Next we'll add a command to your script that players can use to spawn a vehicle beside their position. You may skip it and check out more advanced scripting with the [[Map manager|Map Manager]], which continues this tutorial. Another branch from this tutorial is [[Introduction to Scripting GUI]], you may follow it to see how Graphical User Interface in MTA is drawn and scripted.<br />
<br />
==Creating a simple command==<br />
Let's go back to the content of the ''script.lua'' file. As mentioned above, we want to provide a command to create a vehicle beside your current position in the game. Firstly we need to create a function we want to call and a command handler that creates the command the player will be able to enter in the console.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- create the function the command handler calls, with the arguments: thePlayer, command, vehicleModel<br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- create a vehicle and stuff<br />
end<br />
<br />
-- create a command handler<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
''Note: Function names are clickable in code examples on the wiki and linked to the functions' documentation.''<br />
<br />
====About command handlers====<br />
The first argument of [[addCommandHandler]] is the name of the command the player will be able to enter, the second argument is the function this will call, in this case ''createVehicleForPlayer''.<br />
<br />
If you have already experience in scripting, you will know that you call a function like this:<br />
<syntaxhighlight lang="lua"><br />
functionName(argument1, argument2, argument3, ..)<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
functionName(thePlayer, commandName, argument3, ..)<br />
</syntaxhighlight><br />
If we have a closer look on the lower example above, we can see argument1 is thePlayer and argument2 the commandName. thePlayer is simply the one who typed the command, so whatever you call it, the variable will contain the player who activated the command. commandName is simply the command they typed. So if they typed "/greet", this argument will contain "greet". Argument 3 is something extra the player typed, you'll learn it a little bit further in the tutorial. Never forget that the first 2 arguments are standard arguments, but you can name them to anything you want.<br />
<br />
We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.<br />
<br />
For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:<br />
<syntaxhighlight lang="lua"><br />
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer is the player element of the player who entered the command<br />
</syntaxhighlight><br />
As we can see, it provides several parameters: the player who called the command, the command he entered and whatever text he had after that, in this case "468" as vehicle id for the Sanchez. The first two parameters are the same with all command handlers, which you can read on the [[addEventHandler]] page. For this fact, you always have to define at least those two parameters to use any after that (for example to process text that was entered after the command, like in our example the vehicle model id).<br />
<br />
''Note: You have to add the command handler AFTER you defined the handler function, else it can't find it. The order of execution matters.''<br />
<br />
====Writing the function====<br />
In order to fill the function we created, we need to think about what we have to do:<br />
* Get the players position, so we know where to spawn the vehicle (we want it to appear right beside the player)<br />
* Calculate the position we want to spawn the vehicle at (we don't want it to appear in the player)<br />
* Spawn the vehicle<br />
* Check if it has been spawned successfully, or output a message<br />
<br />
In order to achieve our goals, we have to use several functions. To find function we need to use, we should visit the [[Scripting Functions|Server Functions List]]. First we need a function to get the players position. Since players are Elements, we first jump to the '''Element functions''' where we find the [[getElementPosition]] function. By clicking on the function name in the list, you get to the function description. There we can see the syntax, what it returns and usually an example. The syntax shows us what arguments we can or have to submit.<br />
<br />
For [[getElementPosition]], the syntax is:<br />
<syntaxhighlight lang="lua"><br />
float, float, float getElementPosition ( element theElement )<br />
</syntaxhighlight><br />
<br />
The three ''float'' in front of the function name are the return type. In this case it means the function returns three floating point numbers. (x, y and z) Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
-- get the position and put it in the x,y,z variables<br />
-- (local means, the variables only exist in the current scope, in this case, the function)<br />
local x,y,z = getElementPosition(thePlayer)<br />
end<br />
</syntaxhighlight><br />
<br />
Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the ''x'' variable, which will make it spawn east from the player.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
end<br />
</syntaxhighlight><br />
<br />
Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.<br />
<br />
We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.<br />
<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
end<br />
</syntaxhighlight><br />
<br />
Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.<br />
<br />
Now we have our complete script:<br />
<syntaxhighlight lang="lua"><br />
function createVehicleForPlayer(thePlayer, command, vehicleModel)<br />
local x,y,z = getElementPosition(thePlayer) -- get the position of the player<br />
x = x + 5 -- add 5 units to the x position<br />
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)<br />
-- check if the return value was ''false''<br />
if (createdVehicle == false) then<br />
-- if so, output a message to the chatbox, but only to this player.<br />
outputChatBox("Failed to create vehicle.",thePlayer)<br />
end<br />
end<br />
addCommandHandler("createvehicle", createVehicleForPlayer)<br />
</syntaxhighlight><br />
<br />
As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].<br />
<br />
==What you need to know==<br />
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.<br />
===Clientside and Serverside scripts===<br />
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.<br />
<br />
Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:<br />
<syntaxhighlight lang="xml"><br />
<script src="client.lua" type="client" /><br />
</syntaxhighlight><br />
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].<br />
<br />
===More complex resources===<br />
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:<br />
<br />
====First example - A utility script====<br />
<syntaxhighlight lang="xml"><br />
/admin_commands<br />
/meta.xml<br />
/commands.lua<br />
/client.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="admin commands" /><br />
<script src="commands.lua" /><br />
<script src="client.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server<br />
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily<br />
<br />
This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.<br />
<br />
====Second example - A gamemode====<br />
<syntaxhighlight lang="xml"><br />
/counterstrike<br />
/meta.xml<br />
/counterstrike.lua<br />
/buymenu.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike remake" type="gamemode" /><br />
<script src="counterstrike.lua" /><br />
<script src="buymenu.lua" type="client" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''counterstrike.lua'' contains similiar to the following features:<br />
** Let players choose their team and spawn them<br />
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)<br />
** Define the game's rules, e.g. when does the round end, what happens when a player dies<br />
** .. and maybe some more<br />
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons<br />
<br />
This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.<br />
<br />
This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.<br />
<br />
====Third example - A Map====<br />
<syntaxhighlight lang="xml"><br />
/cs-airport<br />
/meta.xml<br />
/airport.map<br />
/airport.lua<br />
</syntaxhighlight><br />
<syntaxhighlight lang="xml"><br />
<meta><br />
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" /><br />
<map src="airport.map" /><br />
<script src="airport.lua" /><br />
</meta><br />
</syntaxhighlight><br />
<br />
* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:<br />
** Where the players should spawn, with what weapons, what teams there are<br />
** What the targets are<br />
** Weather, World Time, Timelimit<br />
** Provide vehicles<br />
* The ''airport.lua'' might contain map-specific features, that may include:<br />
** Opening some door/make something explode when something specific happens<br />
** Create or move some custom objects, or manipulate objects that are created through the .map file<br />
** .. anything else map-specific you can think of<br />
<br />
As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.<br />
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.<br />
<br />
The ''airport.map'' file might look similiar to this:<br />
<syntaxhighlight lang="xml"><br />
<map mode="deathmatch" version="1.0"><br />
<terrorists><br />
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" /><br />
</terrorists><br />
<counterterrorists><br />
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" /><br />
</counterterrorists><br />
<br />
<bomb posX="23342.23" posY="" posZ="" /><br />
<br />
<vehicle posX="" posY="" posZ="" model="602" /> <br />
<vehicle posX="" posY="" posZ="" model="603" /> <br />
</map><br />
</syntaxhighlight><br />
<br />
When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.<br />
<br />
===Events===<br />
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].<br />
<br />
This example will output a message with the name of the player who died:<br />
<syntaxhighlight lang="lua"><br />
function playerDied(totalAmmo, killer, killerWeapon, bodypart)<br />
outputChatBox(getPlayerName(source).." died!")<br />
end<br />
addEventHandler("onPlayerWasted",getRootElement(),playerDied)<br />
</syntaxhighlight><br />
<br />
Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.<br />
<br />
==Where to go from here==<br />
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.<br />
{{note|From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.}}<br />
'''See also:'''<br />
* [[Advanced Topics]]<br />
[[es:Introducción a la Programación]]<br />
[[it:Introduzione allo scripting]]<br />
[[nl:Scripting_introductie]]<br />
[[pt-br:Introdução ao Scripting]]<br />
[[ru:Scripting Introduction]]<br />
[[ar:مقدمه_في_البرمجه]]</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/Main_Page&diff=37535ZH-CN/Main Page2013-11-10T16:41:40Z<p>JoeZhao: </p>
<hr />
<div>{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
<div style="/*border: 1px solid #D8D8D8;*/ padding-left: 15px; padding-right: 15px; height: 100%;"><br />
[[File:Mtalogo.png|left|100px|link=http://wiki.multitheftauto.com/]]'''欢迎来到 [[Multi Theft Auto]] Wiki。'''您可以在这里查询与 Multi Theft Auto 游戏及开发有关的任何相关信息。<br />
<br />
您可以'''创建地图及游戏模式'''；帮助我们'''编写脚本 API 文档'''、'''示例代码'''及'''教程'''；或是将'''游戏过程中所发现的 Bugs 告诉我们'''。<br />
<br />
如果您在编写脚本时遇到了问题，欢迎随时[[IRC Channel|联系我们]]。<br />
<br/><br/>[ 从此不再一个人玩 ]<br />
<br />
</div><br />
|}<br />
{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
|-<br />
|width="50%" style="vertical-align:top;" |<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px; background: #FFFCF2;"><br />
<div style="float:right; width: 32px;">[[File:Input-gaming.png|link=]]</div><br />
<h3>开始游戏</h3><br />
<div style="background: #FFEEAA; border: 1px solid #FFCD19;"><br />
[[File:Go-down.png|link=http://multitheftauto.googlecode.com/files/mtasa-1.3.4.exe/]] ''' [http://multitheftauto.googlecode.com/files/mtasa-1.3.4.exe/ 下载 Multi Theft Auto: San Andreas 1.3.4 ]'''</div><br />
* [[客户端手册]]<br />
* [[1.3.4 版本新特性]]<br />
* [[已知问题]]<br />
* [[从 MTA:Race 升级到 MTA:SA 1.3]]<br />
* [[服务端手册]]<br />
* [[地图管理器]]<br />
<br />
<h3>地图编辑器</h3><br />
*[[Resource:Editor|地图编辑器手册]]<br />
*[[Resource:Editor/EDF|编辑器定义格式 (EDF)]]<br />
*[[Resource:Editor/Plugins|插件]]<br />
*[[Resource:Editor#FAQ|常见问题解答]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Package-x-generic.png|link=]]</div><br />
<h3>数据库</h3><br />
本节介绍了有关 MTA 或其资源所提供的 Lua 兼容资源。<br />
* [[:Category:Resource|示例资源]] - 学习编写各类脚本的必经之路<br />
* [[客户端脚本]]<br />
* [[扩展模块]]<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Applications-development.png|link=]]</div><br />
<h3>二次开发 Multi Theft Auto</h3><br />
[[File:Go-down.png|link=http://nightly.mtasa.com/]] [http://nightly.mtasa.com/ Nightly builds]<br />
* [[Compiling_MTASA|在 Windows 平台上编译 MTASA]]<br />
* [[Building_MTASA_Server_on_Mac_OS_X|在 Mac OS X 平台上编译 MTA SA]]<br />
* [[Building_MTASA_Server_on_GNU_Linux|在 GNU/Linux 平台上编译 MTA SA]]<br />
* [http://wiki.multitheftauto.com/wiki/Coding_guidelines/ 二次开发指南]<br />
* [http://code.google.com/p/mtasa-blue Google Code SVN]<br />
* [[路线图]]<br />
* [http://bugs.mtasa.com/ Bug 追踪器]<br />
* [[开发分支]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Applications-office.png|link=]]</div><br />
<h3>Wiki - 您能够帮助我们</h3><br />
* 编写完全[[:Category:Incomplete|尚未完成的 API 文档]]。<br />
* [[:Category:Needs_Example |添加 API 及事件的使用示例代码]]。<br />
* 审查及核实[[:Category:Needs Checking|需要检查的页面]]。<br />
* 编写帮助新手的各类教程。<br />
* 将各 Wiki 页面翻译为您所使用的语言。<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Internet-group-chat.png|link=]]</div><br />
<h3>社区</h3><br />
* [http://forum.multitheftauto.com/ MTA 官方论坛]<br />
* IRC: [irc://irc.multitheftauto.com/mta irc.multitheftauto.com #mta]<br />
* [http://community.mtasa.com/ MTA Community] - 分享及资源下载。<br />
* [http://twitter.com/#!/MTAQA/ Twitter] - [http://www.youtube.com/user/MTAQA Youtube] - [http://plus.google.com/102014133442331779727/ Google+] - [http://www.moddb.com/mods/multi-theft-auto-san-andreas ModDB]<br />
</div><br />
<br />
| width="50%" style="vertical-align:top;" |<br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Accessories-text-editor.png|link=]]</div><br />
<h3>脚本编写</h3><br />
* [[Scripting Introduction|脚本编写介绍]]<br />
* [[图形操作界面 (GUI) 脚本编写介绍]]<br />
* [[Debugging|脚本调试教程]] - 用以找出脚本中的错误<br />
* [[Resources|资源介绍]]<br />
** [[访问 Web 资源]] - 如何将资源信息写入网站中<br />
** [[:Category:Resource|示例资源]]<br />
** [[Meta.xml]] - 用于定义资源的描述文件<br />
** [[ACL]] - 访问控制列表 (Access Control List)，用于控制玩家及脚本的各类访问权限<br />
* [[Writing_Gamemodes|编写游戏模式]]<br />
* [[Useful_Functions|常用 API]]<br />
* [http://forum.mtasa.com/viewtopic.php?f=13&t=29363 离线 Wiki]<br />
<div style="float:right; width: 32px;">[[File:start-here.png|link=]]</div><br />
<h3>Lua</h3><br />
了解脚本编写所使用的语言 —— Lua。<br />
*[http://www.lua.org/pil/index.html Lua编程 手册]<br />
**[http://www.lua.org/manual/5.1/#index Lua函数参考]<br />
*[http://lua-users.org/wiki/TutorialDirectory Lua Wiki]<br />
*[http://nixstaller.berlios.de/manual/0.2/nixstaller_9.html 从Nixstaller到Lua的指南]<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px; background:#F2F2FF;"><br />
<div style="float:right; width: 32px;">[[File:Preferences-system.png|link=]]</div><br />
<h3>脚本编写参考</h3><br />
* [[Client Scripting Functions|客户端脚本 API]]<br />
* [[Client Scripting Events|客户端事件]]<br />
* [[Server Scripting Functions|服务端脚本 API]]<br />
* [[Server Scripting Events|服务端事件]]<br />
<!-- Incomplete * [[Module functions|服务器端外部模块的脚本功能列表]] --><br />
* [[MTA 类]] - 详细列明 MTA 中所有的自定义元素类型<br />
** [[Element|MTA 元素]] / [[元素树]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:System-file-manager.png|link=]]</div><br />
<h3>[[Id|ID 列表]]</h3><br />
*[[动作]]<br />
*[[任务皮肤]]<br />
*[[CJ衣服|服饰]]<br />
*[[车库|车库]]<br />
*[[室内控件]]<br />
*[[材质]]<br />
*[[弹射物体]]<br />
*[[雷达图标]]<br />
*[[声音及音效]]<br />
*[[交通工具]]<br />
*[[交通工具颜色]]<br />
*[[交通工具组件]]<br />
*[[车辆变体|交通工具改装组件]]<br />
*[[交通工具改装操纵]]<br />
*[[武器|武器]]<br />
*[[天气]]<br />
</div><br />
<div style="padding:4px 8px 8px 8px; margin:10px;"><br />
[[File:Osi symbol.png|75px|link=http://opensource.org/|left]]<br />
'''Multi Theft Auto''' 是'''一个开源项目'''。 <br />
<br/>任何人都可以为 MTA 作出更多的贡献！<br />
</div><br />
|-<br />
| colspan="2" |<br />
|}<br />
{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
<div style="padding-left: 15px; padding-right: 15px;" class="plainlinks"><br />
[[File:MTALogo_8ball.png|left|85px|link=Archive]]<br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''关于 [[Multi Theft Auto]]'''</li><br />
<li>[[档案]]</li><br />
<li>[[新闻报道]]</li><br />
<li>[http://code.google.com/p/mtasa-blue/people/list 开发者]</li><br />
</ul><br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''Multi Theft Auto 0.5'''</li><br />
<li>[[Archive#Multi_Theft_Auto_0.5|下载]]</li><br />
<li>[[MTA 0.5r2 Known Issues|已知问题]]</li><br />
</ul><br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''Wiki 统计'''</li><br />
<li>共 {{NUMBEROFARTICLES}} 篇文章</li><br />
<li>共 {{NUMBEROFPAGES}} 页页面</li><br />
<li>共 {{NUMBEROFUSERS}} 位注册用户</li><br />
</ul><br />
</div><br />
|}<br />
<br />
__NOTOC__<br />
__NOEDITSECTION__<br />
{{Languages list|en}}</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/Main_Page&diff=37534ZH-CN/Main Page2013-11-10T16:38:24Z<p>JoeZhao: </p>
<hr />
<div>{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
<div style="/*border: 1px solid #D8D8D8;*/ padding-left: 15px; padding-right: 15px; height: 100%;"><br />
[[File:Mtalogo.png|left|100px|link=http://wiki.multitheftauto.com/]]'''欢迎来到 [[Multi Theft Auto]] Wiki。'''您可以在这里查询与 Multi Theft Auto 游戏以及开发有关的任何信息。<br />
<br />
您可以'''创建地图'''、'''游戏模式'''；帮助我们'''编写脚本 API 文档'''、'''示例代码'''及'''教程'''；或是将'''游戏过程中所发现的 bugs 告诉我们'''。<br />
<br />
如果您在编写脚本时遇到了问题，欢迎随时[[IRC Channel|联系我们]]。<br />
<br/><br/>[ 从此不再一个人玩 ]<br />
<br />
</div><br />
|}<br />
{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
|-<br />
|width="50%" style="vertical-align:top;" |<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px; background: #FFFCF2;"><br />
<div style="float:right; width: 32px;">[[File:Input-gaming.png|link=]]</div><br />
<h3>开始游戏</h3><br />
<div style="background: #FFEEAA; border: 1px solid #FFCD19;"><br />
[[File:Go-down.png|link=http://multitheftauto.googlecode.com/files/mtasa-1.3.4.exe/]] ''' [http://multitheftauto.googlecode.com/files/mtasa-1.3.4.exe/ 下载 Multi Theft Auto: San Andreas 1.3.4 ]'''</div><br />
* [[客户端手册]]<br />
* [[1.3.4 版本新特性]]<br />
* [[已知问题]]<br />
* [[从 MTA:Race 升级到 MTA:SA 1.3]]<br />
* [[服务端手册]]<br />
* [[地图管理器]]<br />
<br />
<h3>地图编辑器</h3><br />
*[[Resource:Editor|地图编辑器手册]]<br />
*[[Resource:Editor/EDF|编辑器定义格式 (EDF)]]<br />
*[[Resource:Editor/Plugins|插件]]<br />
*[[Resource:Editor#FAQ|常见问题解答]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Package-x-generic.png|link=]]</div><br />
<h3>数据库</h3><br />
本节介绍了有关 MTA 或其资源所提供的 Lua 兼容资源。<br />
* [[:Category:Resource|示例资源]] - 学习编写各类脚本的必经之路<br />
* [[客户端脚本]]<br />
* [[扩展模块]]<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Applications-development.png|link=]]</div><br />
<h3>二次开发 Multi Theft Auto</h3><br />
[[File:Go-down.png|link=http://nightly.mtasa.com/]] [http://nightly.mtasa.com/ Nightly builds]<br />
* [[Compiling_MTASA|在 Windows 平台上编译 MTASA]]<br />
* [[Building_MTASA_Server_on_Mac_OS_X|在 Mac OS X 平台上编译 MTA SA]]<br />
* [[Building_MTASA_Server_on_GNU_Linux|在 GNU/Linux 平台上编译 MTA SA]]<br />
* [http://wiki.multitheftauto.com/wiki/Coding_guidelines/ 二次开发指南]<br />
* [http://code.google.com/p/mtasa-blue Google Code SVN]<br />
* [[路线图]]<br />
* [http://bugs.mtasa.com/ Bug 追踪器]<br />
* [[开发分支]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Applications-office.png|link=]]</div><br />
<h3>Wiki - 您能够帮助我们</h3><br />
* 编写完全[[:Category:Incomplete|尚未完成的 API 文档]]。<br />
* [[:Category:Needs_Example |添加 API 及事件的使用示例代码]]。<br />
* 审查及核实[[:Category:Needs Checking|需要检查的页面]]。<br />
* 编写帮助新手的各类教程。<br />
* 将各 Wiki 页面翻译为您所使用的语言。<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Internet-group-chat.png|link=]]</div><br />
<h3>社区</h3><br />
* [http://forum.multitheftauto.com/ MTA 官方论坛]<br />
* IRC: [irc://irc.multitheftauto.com/mta irc.multitheftauto.com #mta]<br />
* [http://community.mtasa.com/ MTA Community] - 分享及资源下载。<br />
* [http://twitter.com/#!/MTAQA/ Twitter] - [http://www.youtube.com/user/MTAQA Youtube] - [http://plus.google.com/102014133442331779727/ Google+] - [http://www.moddb.com/mods/multi-theft-auto-san-andreas ModDB]<br />
</div><br />
<br />
| width="50%" style="vertical-align:top;" |<br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Accessories-text-editor.png|link=]]</div><br />
<h3>脚本编写</h3><br />
* [[Scripting Introduction|脚本编写介绍]]<br />
* [[图形操作界面 (GUI) 脚本编写介绍]]<br />
* [[Debugging|脚本调试教程]] - 用以找出脚本中的错误<br />
* [[Resources|资源介绍]]<br />
** [[访问 Web 资源]] - 如何将资源信息写入网站中<br />
** [[:Category:Resource|示例资源]]<br />
** [[Meta.xml]] - 用于定义资源的描述文件<br />
** [[ACL]] - 访问控制列表 (Access Control List)，用于控制玩家及脚本的各类访问权限<br />
* [[Writing_Gamemodes|编写游戏模式]]<br />
* [[Useful_Functions|常用 API]]<br />
* [http://forum.mtasa.com/viewtopic.php?f=13&t=29363 离线 Wiki]<br />
<div style="float:right; width: 32px;">[[File:start-here.png|link=]]</div><br />
<h3>Lua</h3><br />
了解脚本编写所使用的语言 —— Lua。<br />
*[http://www.lua.org/pil/index.html Lua编程 手册]<br />
**[http://www.lua.org/manual/5.1/#index Lua函数参考]<br />
*[http://lua-users.org/wiki/TutorialDirectory Lua Wiki]<br />
*[http://nixstaller.berlios.de/manual/0.2/nixstaller_9.html 从Nixstaller到Lua的指南]<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px; background:#F2F2FF;"><br />
<div style="float:right; width: 32px;">[[File:Preferences-system.png|link=]]</div><br />
<h3>脚本编写参考</h3><br />
* [[Client Scripting Functions|客户端脚本 API]]<br />
* [[Client Scripting Events|客户端事件]]<br />
* [[Server Scripting Functions|服务端脚本 API]]<br />
* [[Server Scripting Events|服务端事件]]<br />
<!-- Incomplete * [[Module functions|服务器端外部模块的脚本功能列表]] --><br />
* [[MTA 类]] - 详细列明 MTA 中所有的自定义元素类型<br />
** [[Element|MTA 元素]] / [[元素树]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:System-file-manager.png|link=]]</div><br />
<h3>[[Id|ID 列表]]</h3><br />
*[[动作]]<br />
*[[任务皮肤]]<br />
*[[CJ衣服|服饰]]<br />
*[[车库|车库]]<br />
*[[室内控件]]<br />
*[[材质]]<br />
*[[弹射物体]]<br />
*[[雷达图标]]<br />
*[[声音及音效]]<br />
*[[交通工具]]<br />
*[[交通工具颜色]]<br />
*[[交通工具组件]]<br />
*[[车辆变体|交通工具改装组件]]<br />
*[[交通工具改装操纵]]<br />
*[[武器|武器]]<br />
*[[天气]]<br />
</div><br />
<div style="padding:4px 8px 8px 8px; margin:10px;"><br />
[[File:Osi symbol.png|75px|link=http://opensource.org/|left]]<br />
'''Multi Theft Auto'''是'''一个开源项目'''。 <br />
<br/>任何人都可以为 MTA 作出更多的贡献！<br />
</div><br />
|-<br />
| colspan="2" |<br />
|}<br />
{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
<div style="padding-left: 15px; padding-right: 15px;" class="plainlinks"><br />
[[File:MTALogo_8ball.png|left|85px|link=Archive]]<br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''关于 [[Multi Theft Auto]]'''</li><br />
<li>[[档案]]</li><br />
<li>[[新闻报道]]</li><br />
<li>[http://code.google.com/p/mtasa-blue/people/list 开发者]</li><br />
</ul><br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''Multi Theft Auto 0.5'''</li><br />
<li>[[Archive#Multi_Theft_Auto_0.5|下载]]</li><br />
<li>[[MTA 0.5r2 Known Issues|已知问题]]</li><br />
</ul><br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''Wiki 统计'''</li><br />
<li>共 {{NUMBEROFARTICLES}} 篇文章</li><br />
<li>共 {{NUMBEROFPAGES}} 页页面</li><br />
<li>共 {{NUMBEROFUSERS}} 位注册用户</li><br />
</ul><br />
</div><br />
|}<br />
<br />
__NOTOC__<br />
__NOEDITSECTION__<br />
{{Languages list|en}}</div>JoeZhaohttps://wiki.multitheftauto.com/index.php?title=ZH-CN/Main_Page&diff=37533ZH-CN/Main Page2013-11-10T16:34:50Z<p>JoeZhao: </p>
<hr />
<div>{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
<div style="/*border: 1px solid #D8D8D8;*/ padding-left: 15px; padding-right: 15px; height: 100%;"><br />
[[File:Mtalogo.png|left|100px|link=http://wiki.multitheftauto.com/]]'''欢迎来到 [[Multi Theft Auto]] Wiki。''' 您可以在这里查询与 Multi Theft Auto 游戏以及开发有关的任何信息。<br />
<br />
您可以'''创建地图'''、'''游戏模式'''；帮助我们'''编写脚本 API 文档'''、'''示例代码'''及'''教程'''；或是将'''游戏过程中所发现的 bugs 告诉我们'''。<br />
<br />
如果您在编写脚本时遇到了问题，欢迎随时[[IRC Channel|联系我们]]。<br />
<br/><br/>[ 从此不再一个人玩 ]<br />
<br />
</div><br />
|}<br />
{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
|-<br />
|width="50%" style="vertical-align:top;" |<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px; background: #FFFCF2;"><br />
<div style="float:right; width: 32px;">[[File:Input-gaming.png|link=]]</div><br />
<h3>开始游戏</h3><br />
<div style="background: #FFEEAA; border: 1px solid #FFCD19;"><br />
[[File:Go-down.png|link=http://multitheftauto.googlecode.com/files/mtasa-1.3.4.exe/]] ''' [http://multitheftauto.googlecode.com/files/mtasa-1.3.4.exe/ 下载 Multi Theft Auto: San Andreas 1.3.4 ]'''</div><br />
* [[客户端手册]]<br />
* [[1.3.4 版本新特性]]<br />
* [[已知问题]]<br />
* [[从 MTA:Race 升级到 MTA:SA 1.3]]<br />
* [[服务端手册]]<br />
* [[地图管理器]]<br />
<br />
<h3>地图编辑器</h3><br />
*[[Resource:Editor|地图编辑器手册]]<br />
*[[Resource:Editor/EDF|编辑器定义格式 (EDF)]]<br />
*[[Resource:Editor/Plugins|插件]]<br />
*[[Resource:Editor#FAQ|常见问题解答]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Package-x-generic.png|link=]]</div><br />
<h3>数据库</h3><br />
本节介绍了有关 MTA 或其资源所提供的 Lua 兼容资源。<br />
* [[:Category:Resource|示例资源]] - 学习编写各类脚本的必经之路<br />
* [[客户端脚本]]<br />
* [[扩展模块]]<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Applications-development.png|link=]]</div><br />
<h3>二次开发 Multi Theft Auto</h3><br />
[[File:Go-down.png|link=http://nightly.mtasa.com/]] [http://nightly.mtasa.com/ Nightly builds]<br />
* [[Compiling_MTASA|在 Windows 平台上编译 MTASA]]<br />
* [[Building_MTASA_Server_on_Mac_OS_X|在 Mac OS X 平台上编译 MTA SA]]<br />
* [[Building_MTASA_Server_on_GNU_Linux|在 GNU/Linux 平台上编译 MTA SA]]<br />
* [http://wiki.multitheftauto.com/wiki/Coding_guidelines/ 二次开发指南]<br />
* [http://code.google.com/p/mtasa-blue Google Code SVN]<br />
* [[路线图]]<br />
* [http://bugs.mtasa.com/ Bug 追踪器]<br />
* [[开发分支]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Applications-office.png|link=]]</div><br />
<h3>Wiki - 您能够帮助我们</h3><br />
* 编写完全[[:Category:Incomplete|尚未完成的 API 文档]]。<br />
* [[:Category:Needs_Example |添加 API 及事件的使用示例代码]]。<br />
* 审查及核实[[:Category:Needs Checking|需要检查的页面]]。<br />
* 编写帮助新手的各类教程。<br />
* 将各 Wiki 页面翻译为您所使用的语言。<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Internet-group-chat.png|link=]]</div><br />
<h3>社区</h3><br />
* [http://forum.multitheftauto.com/ MTA 官方论坛]<br />
* IRC: [irc://irc.multitheftauto.com/mta irc.multitheftauto.com #mta]<br />
* [http://community.mtasa.com/ MTA Community] - 分享及资源下载。<br />
* [http://twitter.com/#!/MTAQA/ Twitter] - [http://www.youtube.com/user/MTAQA Youtube] - [http://plus.google.com/102014133442331779727/ Google+] - [http://www.moddb.com/mods/multi-theft-auto-san-andreas ModDB]<br />
</div><br />
<br />
| width="50%" style="vertical-align:top;" |<br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:Accessories-text-editor.png|link=]]</div><br />
<h3>脚本编写</h3><br />
* [[Scripting Introduction|脚本编写介绍]]<br />
* [[图形操作界面 (GUI) 脚本编写介绍]]<br />
* [[Debugging|脚本调试教程]] - 用以找出脚本中的错误<br />
* [[Resources|资源介绍]]<br />
** [[访问 Web 资源]] - 如何将资源信息写入网站中<br />
** [[:Category:Resource|示例资源]]<br />
** [[Meta.xml]] - 用于定义资源的描述文件<br />
** [[ACL]] - 访问控制列表 (Access Control List)，用于控制玩家及脚本的各类访问权限<br />
* [[Writing_Gamemodes|编写游戏模式]]<br />
* [[Useful_Functions|常用 API]]<br />
* [http://forum.mtasa.com/viewtopic.php?f=13&t=29363 离线 Wiki]<br />
<div style="float:right; width: 32px;">[[File:start-here.png|link=]]</div><br />
<h3>Lua</h3><br />
了解脚本编写所使用的语言 —— Lua。<br />
*[http://www.lua.org/pil/index.html Lua编程 手册]<br />
**[http://www.lua.org/manual/5.1/#index Lua函数参考]<br />
*[http://lua-users.org/wiki/TutorialDirectory Lua Wiki]<br />
*[http://nixstaller.berlios.de/manual/0.2/nixstaller_9.html 从Nixstaller到Lua的指南]<br />
</div><br />
<br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px; background:#F2F2FF;"><br />
<div style="float:right; width: 32px;">[[File:Preferences-system.png|link=]]</div><br />
<h3>脚本编写参考</h3><br />
* [[Client Scripting Functions|客户端脚本 API]]<br />
* [[Client Scripting Events|客户端事件]]<br />
* [[Server Scripting Functions|服务端脚本 API]]<br />
* [[Server Scripting Events|服务端事件]]<br />
<!-- Incomplete * [[Module functions|服务器端外部模块的脚本功能列表]] --><br />
* [[MTA 类]] - 详细列明 MTA 中所有的自定义元素类型<br />
** [[Element|MTA 元素]] / [[元素树]]<br />
</div><br />
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;"><br />
<div style="float:right; width: 32px;">[[File:System-file-manager.png|link=]]</div><br />
<h3>[[Id|ID 列表]]</h3><br />
*[[动作]]<br />
*[[任务皮肤]]<br />
*[[CJ衣服|服饰]]<br />
*[[车库|车库]]<br />
*[[室内控件]]<br />
*[[材质]]<br />
*[[弹射物体]]<br />
*[[雷达图标]]<br />
*[[声音及音效]]<br />
*[[交通工具]]<br />
*[[交通工具颜色]]<br />
*[[交通工具组件]]<br />
*[[车辆变体|交通工具改装组件]]<br />
*[[交通工具改装操纵]]<br />
*[[武器|武器]]<br />
*[[天气]]<br />
</div><br />
<div style="padding:4px 8px 8px 8px; margin:10px;"><br />
[[File:Osi symbol.png|75px|link=http://opensource.org/|left]]<br />
'''Multi Theft Auto'''是'''一个开源项目'''。 <br />
<br/>任何人都可以为 MTA 作出更多的贡献！<br />
</div><br />
|-<br />
| colspan="2" |<br />
|}<br />
{| width="100%" cellspacing="0" cellpadding="0"<br />
| colspan="2" |<br />
<div style="padding-left: 15px; padding-right: 15px;" class="plainlinks"><br />
[[File:MTALogo_8ball.png|left|85px|link=Archive]]<br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''关于[[Multi Theft Auto]]'''</li><br />
<li>[[档案]]</li><br />
<li>[[新闻报道]]</li><br />
<li>[http://code.google.com/p/mtasa-blue/people/list 开发者列表]</li><br />
</ul><br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''Multi Theft Auto 0.5'''</li><br />
<li>[[Archive#Multi_Theft_Auto_0.5|下载]]</li><br />
<li>[[MTA 0.5r2 Known Issues|已知错误]]</li><br />
</ul><br />
<ul style="list-style: none; width: 200px; float: left;"><br />
<li>'''维基统计'''</li><br />
<li>{{NUMBEROFARTICLES}} 文章</li><br />
<li>{{NUMBEROFPAGES}} 页面</li><br />
<li>{{NUMBEROFUSERS}} 注册用户</li><br />
</ul><br />
</div><br />
|}<br />
<br />
__NOTOC__<br />
__NOEDITSECTION__<br />
{{Languages list|en}}</div>JoeZhao