summaryrefslogtreecommitdiffstats
path: root/MCServer/Plugins/APIDump
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--MCServer/Plugins/APIDump/APIDesc.lua94
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua24
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnProjectileHitEntity.lua25
-rw-r--r--MCServer/Plugins/APIDump/SettingUpZeroBrane.html46
-rw-r--r--MCServer/Plugins/APIDump/Static/zbs_logo.pngbin0 -> 1306 bytes
-rw-r--r--MCServer/Plugins/APIDump/Static/zbs_workspace.pngbin0 -> 72631 bytes
-rw-r--r--MCServer/Plugins/APIDump/main_APIDump.lua4
7 files changed, 179 insertions, 14 deletions
diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua
index 01f000182..b3b7dd11c 100644
--- a/MCServer/Plugins/APIDump/APIDesc.lua
+++ b/MCServer/Plugins/APIDump/APIDesc.lua
@@ -200,6 +200,8 @@ g_APIDesc =
msFillAir = { Notes = "Dst is overwritten by Src only where Src has air blocks" },
msImprint = { Notes = "Src overwrites Dst anywhere where Dst has non-air blocks" },
msLake = { Notes = "Special mode for merging lake images" },
+ msSpongePrint = { Notes = "Similar to msImprint, sponge block doesn't overwrite anything, all other blocks overwrite everything"},
+ msMask = { Notes = "The blocks that are exactly the same are kept in Dst, all differing blocks are replaced by air"},
},
ConstantGroups =
{
@@ -247,6 +249,9 @@ g_APIDesc =
<tr>
<td> A </td><td> B </td><td> B </td><td> A </td><td> B </td>
</tr>
+ <tr>
+ <td> A </td><td> A </td><td> A </td><td> A </td><td> A </td>
+ </td>
</tbody></table>
<p>
@@ -258,12 +263,24 @@ g_APIDesc =
</ol>
</p>
+ <h3>Special strategies</h3>
+ <p>For each strategy, evaluate the table rows from top downwards, the first match wins.</p>
+
<p>
- Special strategies:
+ <strong>msDifference</strong> - changes all the blocks which are the same to air. Otherwise the source block gets placed.
</p>
-
+ <table><tbody<tr>
+ <th colspan="2"> area block </th><th> </th><th> Notes </th>
+ </tr><tr>
+ <td> * </td><td> B </td><td> B </td><td> The blocks are different so we use block B </td>
+ </tr><tr>
+ <td> B </td><td> B </td><td> Air </td><td> The blocks are the same so we get air. </td>
+ </tr>
+ </tbody></table>
+
+
<p>
- <strong>msLake</strong> (evaluate top-down, first match wins):
+ <strong>msLake</strong> - used for merging areas with lava and water lakes, in the appropriate generator.
</p>
<table><tbody><tr>
<th colspan="2"> area block </th><th> </th><th> Notes </th>
@@ -293,7 +310,39 @@ g_APIDesc =
<td> A </td><td> * </td><td> A </td><td> Everything else is left as it is </td>
</tr>
</tbody></table>
- ]],
+
+ <p>
+ <strong>msSpongePrint</strong> - used for most prefab-generators to merge the prefabs. Similar to
+ msImprint, but uses the sponge block as the NOP block instead, so that the prefabs may carve out air
+ pockets, too.
+ </p>
+ <table><tbody><tr>
+ <th colspan="2"> area block </th><th> </th><th> Notes </th>
+ </tr><tr>
+ <th> this </th><th> Src </th><th> result </th><th> </th>
+ </tr><tr>
+ <td> A </td><td> sponge </td><td> A </td><td> Sponge is the NOP block </td>
+ </tr><tr>
+ <td> * </td><td> B </td><td> B </td><td> Everything else overwrites anything </td>
+ </tr>
+ </tbody></table>
+
+ <p>
+ <strong>msMask</strong> - the blocks that are the same in the other area are kept, all the
+ differing blocks are replaced with air. Meta is used in the comparison, too, two blocks of the
+ same type but different meta are considered different and thus replaced with air.
+ </p>
+ <table><tbody><tr>
+ <th colspan="2"> area block </th><th> </th><th> Notes </th>
+ </tr><tr>
+ <th> this </th><th> Src </th><th> result </th><th> </th>
+ </tr><tr>
+ <td> A </td><td> A </td><td> A </td><td> Same blocks are kept </td>
+ </tr><tr>
+ <td> A </td><td> non-A </td><td> air </td><td> Differing blocks are replaced with air </td>
+ </tr>
+ </tbody></table>
+]],
}, -- Merge strategies
}, -- AdditionalInfo
}, -- cBlockArea
@@ -728,14 +777,14 @@ end</pre>
GetMass = { Params = "", Return = "number", Notes = "Returns the mass of the entity. Currently unused." },
GetMaxHealth = { Params = "", Return = "number", Notes = "Returns the maximum number of hitpoints this entity is allowed to have." },
GetParentClass = { Params = "", Return = "string", Notes = "Returns the name of the direct parent class for this entity" },
- GetPitch = { Params = "", Return = "number", Notes = "Returns the pitch (nose-down rotation) of the entity" },
+ GetPitch = { Params = "", Return = "number", Notes = "Returns the pitch (nose-down rotation) of the entity. Measured in degrees, normal values range from -90 to +90. +90 means looking down, 0 means looking straight ahead, -90 means looking up." },
GetPosition = { Params = "", Return = "{{Vector3d}}", Notes = "Returns the entity's pivot position as a 3D vector" },
GetPosX = { Params = "", Return = "number", Notes = "Returns the X-coord of the entity's pivot" },
GetPosY = { Params = "", Return = "number", Notes = "Returns the Y-coord of the entity's pivot" },
GetPosZ = { Params = "", Return = "number", Notes = "Returns the Z-coord of the entity's pivot" },
GetRawDamageAgainst = { Params = "ReceiverEntity", Return = "number", Notes = "Returns the raw damage that this entity's equipment would cause when attacking the ReceiverEntity. This includes this entity's weapon {{cEnchantments|enchantments}}, but excludes the receiver's armor or potion effects. See {{TakeDamageInfo}} for more information on attack damage." },
GetRoll = { Params = "", Return = "number", Notes = "Returns the roll (sideways rotation) of the entity. Currently unused." },
- GetRot = { Params = "", Return = "{{Vector3f}}", Notes = "Returns the entire rotation vector (Yaw, Pitch, Roll)" },
+ GetRot = { Params = "", Return = "{{Vector3f}}", Notes = "(OBSOLETE) Returns the entire rotation vector (Yaw, Pitch, Roll)" },
GetSpeed = { Params = "", Return = "{{Vector3d}}", Notes = "Returns the complete speed vector of the entity" },
GetSpeedX = { Params = "", Return = "number", Notes = "Returns the X-part of the speed vector" },
GetSpeedY = { Params = "", Return = "number", Notes = "Returns the Y-part of the speed vector" },
@@ -743,7 +792,7 @@ end</pre>
GetUniqueID = { Params = "", Return = "number", Notes = "Returns the ID that uniquely identifies the entity within the running server. Note that this ID is not persisted to the data files." },
GetWidth = { Params = "", Return = "number", Notes = "Returns the width (X and Z size) of the entity." },
GetWorld = { Params = "", Return = "{{cWorld}}", Notes = "Returns the world where the entity resides" },
- GetYaw = { Params = "", Return = "number", Notes = "Returns the yaw (direction) of the entity." },
+ GetYaw = { Params = "", Return = "number", Notes = "Returns the yaw (direction) of the entity. Measured in degrees, values range from -180 to +180. 0 means ZP, 90 means XM, -180 means ZM, -90 means XP." },
Heal = { Params = "Hitpoints", Return = "", Notes = "Heals the specified number of hitpoints. Hitpoints is expected to be a positive number." },
IsA = { Params = "ClassName", Return = "bool", Notes = "Returns true if the entity class is a descendant of the specified class name, or the specified class itself" },
IsBoat = { Params = "", Return = "bool", Notes = "Returns true if the entity is a {{cBoat|boat}}." },
@@ -2647,11 +2696,31 @@ end
ItemToFullString = {Params = "{{cItem|cItem}}", Return = "string", Notes = "Returns the string representation of the item, in the format 'ItemTypeText:ItemDamage * Count'"},
ItemToString = {Params = "{{cItem|cItem}}", Return = "string", Notes = "Returns the string representation of the item type"},
ItemTypeToString = {Params = "ItemType", Return = "string", Notes = "Returns the string representation of ItemType "},
- LOG = {Params = "string", Notes = "Logs a text into the server console using 'normal' severity (gray text) "},
- LOGERROR = {Params = "string", Notes = "Logs a text into the server console using 'error' severity (black text on red background)"},
- LOGINFO = {Params = "string", Notes = "Logs a text into the server console using 'info' severity (yellow text)"},
- LOGWARN = {Params = "string", Notes = "Logs a text into the server console using 'warning' severity (red text); OBSOLETE, use LOGWARNING() instead"},
- LOGWARNING = {Params = "string", Notes = "Logs a text into the server console using 'warning' severity (red text)"},
+ LOG =
+ {
+ {Params = "string", Notes = "Logs a text into the server console using 'normal' severity (gray text)"},
+ {Params = "{{cCompositeChat|CompositeChat}}", Notes = "Logs the {{cCompositeChat}}'s human-readable text into the server console. The severity is converted from the CompositeChat's MessageType."},
+ },
+ LOGERROR =
+ {
+ {Params = "string", Notes = "Logs a text into the server console using 'error' severity (black text on red background)"},
+ {Params = "{{cCompositeChat|CompositeChat}}", Notes = "Logs the {{cCompositeChat}}'s human-readable text into the server console using 'error' severity (black text on red background)"},
+ },
+ LOGINFO =
+ {
+ {Params = "string", Notes = "Logs a text into the server console using 'info' severity (yellow text)"},
+ {Params = "{{cCompositeChat|CompositeChat}}", Notes = "Logs the {{cCompositeChat}}'s human-readable text into the server console using 'info' severity (yellow text)"},
+ },
+ LOGWARN =
+ {
+ {Params = "string", Notes = "Logs a text into the server console using 'warning' severity (red text); OBSOLETE, use LOGWARNING() instead"},
+ {Params = "{{cCompositeChat|CompositeChat}}", Notes = "Logs the {{cCompositeChat}}'s human-readable text into the server console using 'warning' severity (red text); OBSOLETE, use LOGWARNING() instead"},
+ },
+ LOGWARNING =
+ {
+ {Params = "string", Notes = "Logs a text into the server console using 'warning' severity (red text)"},
+ {Params = "{{cCompositeChat|CompositeChat}}", Notes = "Logs the {{cCompositeChat}}'s human-readable text into the server console using 'warning' severity (red text)"},
+ },
MirrorBlockFaceY = { Params = "{{Globals#BlockFaces|eBlockFace}}", Return = "{{Globals#BlockFaces|eBlockFace}}", Notes = "Returns the {{Globals#BlockFaces|eBlockFace}} that corresponds to the given {{Globals#BlockFaces|eBlockFace}} after mirroring it around the Y axis (or rotating 180 degrees around it)." },
NoCaseCompare = {Params = "string, string", Return = "number", Notes = "Case-insensitive string comparison; returns 0 if the strings are the same"},
NormalizeAngleDegrees = { Params = "AngleDegrees", Return = "AngleDegrees", Notes = "Returns the angle, wrapped into the [-180, +180) range." },
@@ -2845,6 +2914,7 @@ end
-- No sorting is provided for these, they will be output in the same order as defined here
{ FileName = "Writing-a-MCServer-plugin.html", Title = "Writing a MCServer plugin" },
{ FileName = "SettingUpDecoda.html", Title = "Setting up the Decoda Lua IDE" },
+ { FileName = "SettingUpZeroBrane.html", Title = "Setting up the ZeroBrane Studio Lua IDE" },
{ FileName = "WebWorldThreads.html", Title = "Webserver vs World threads" },
}
} ;
diff --git a/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua
new file mode 100644
index 000000000..1588d420c
--- /dev/null
+++ b/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua
@@ -0,0 +1,24 @@
+return
+{
+ HOOK_PROJECTILE_HIT_BLOCK =
+ {
+ CalledWhen = "A projectile hits a solid block.",
+ DefaultFnName = "OnProjectileHitBlock", -- also used as pagename
+ Desc = [[
+ This hook is called when a {{cProjectileEntity|projectile}} hits a solid block..
+ ]],
+ Params =
+ {
+ { Name = "ProjectileEntity", Type = "{{cProjectileEntity}}", Notes = "The projectile that hit an entity." },
+ },
+ Returns = [[
+ If the function returns false or no value, the next plugin's callback is called. If the function
+ returns true, no other callback is called for this event and the projectile flies through block..
+ ]],
+ }, -- HOOK_PROJECTILE_HIT_BLOCK
+}
+
+
+
+
+
diff --git a/MCServer/Plugins/APIDump/Hooks/OnProjectileHitEntity.lua b/MCServer/Plugins/APIDump/Hooks/OnProjectileHitEntity.lua
new file mode 100644
index 000000000..dd949fb46
--- /dev/null
+++ b/MCServer/Plugins/APIDump/Hooks/OnProjectileHitEntity.lua
@@ -0,0 +1,25 @@
+return
+{
+ HOOK_PROJECTILE_HIT_ENTITY =
+ {
+ CalledWhen = "A projectile hits another entity.",
+ DefaultFnName = "OnProjectileHitEntity", -- also used as pagename
+ Desc = [[
+ This hook is called when a {{cProjectileEntity|projectile}} hits another entity.
+ ]],
+ Params =
+ {
+ { Name = "ProjectileEntity", Type = "{{cProjectileEntity}}", Notes = "The projectile that hit an entity." },
+ { Name = "Entity", Type = "{{cEntity}}", Notes = "The entity wich was hit." },
+ },
+ Returns = [[
+ If the function returns false or no value, the next plugin's callback is called. If the function
+ returns true, no other callback is called for this event and the projectile flies through the entity.
+ ]],
+ }, -- HOOK_PROJECTILE_HIT_ENTITY
+}
+
+
+
+
+
diff --git a/MCServer/Plugins/APIDump/SettingUpZeroBrane.html b/MCServer/Plugins/APIDump/SettingUpZeroBrane.html
new file mode 100644
index 000000000..4ebbcb6e6
--- /dev/null
+++ b/MCServer/Plugins/APIDump/SettingUpZeroBrane.html
@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+
+<html>
+ <head>
+ <title>MCServer - Setting up ZeroBrane Studio</title>
+ <link rel="stylesheet" type="text/css" href="main.css" />
+ <link rel="stylesheet" type="text/css" href="prettify.css" />
+ <script src="prettify.js"></script>
+ <script src="lang-lua.js"></script>
+ <meta charset="UTF-8">
+ </head>
+ <body>
+ <div id="content">
+ <h1>Setting up the ZeroBrane Studio IDE</h1>
+ <p>
+ This article will explain how to set up ZeroBrane Studio, an IDE for writing Lua code, so that you can develop MCServer plugins with the comfort of an IDE.</p>
+
+ <h2><img src="Static/zbs_logo.png" /> About ZeroBrane Studio</h2>
+
+ <p>To quickly introduce ZeroBrane Studio, it is an IDE for writing Lua code. It has the basic features expected of an IDE - it allows you to manage groups of files as a project, you can edit multiple files in a tabbed editor, the code is syntax-highlighted. Code completion, symbol browsing, and more. It also features a Lua debugger that allows you to debug your Lua code within any application that uses Lua and can load Lua packages. It is written using the multiplatform WxWidgets toolkit, and runs on multiple platforms, including Windows, Linux and MacOS.</p>
+ <p>Here's a screenshot of a default ZBS window with the debugger stepping through the code (scaled down):<br />
+ <img src="Static/zbs_workspace.png" /></p>
+ <p>As you can see, you can set breakpoints in the code, inspect variables' values, view the Lua call-stacks.</p>
+ <p>ZBS is open-source, the sources are on GitHub: <a href="https://github.com/pkulchenko/ZeroBraneStudio">https://github.com/pkulchenko/ZeroBraneStudio</a>. The project's homepage is at <a href="http://studio.zerobrane.com/">http://studio.zerobrane.com/</a>.
+
+ <h2><img src="Static/zbs_logo.png" /> First-time setup</h2>
+ <p>Since ZBS is a universal Lua IDE, you need to first set it up so that it is ready for MCS plugin development. For that, you need to download one file, <a href="https://raw.githubusercontent.com/pkulchenko/ZeroBranePackage/master/mcserver.lua">mcserver.lua</a> from the <a href="https://github.com/pkulchenko/ZeroBranePackage">ZBS's plugin repository</a>. Place that file in the "packages" folder inside your ZBS's folder. Note that there are other useful plugins in the repository and you may want to have a look there later on to further customize your ZBS. To install them, simply save them into the same folder.</p>
+ <p>Next you should install the code-completion support specific for MCServer. You should repeat this step from time to time, because the API evolves in time so new functions and classes are added to it quite often. You should have an APIDump plugin in your MCServer installation. Enable the APIDump plugin in the server settings, it's very cheap to keep it enabled and it doesn't cost any performance during normal gameplay. To generate the code-completion support file, enter the <code style="background: #ddd; border: 1px solid #aaa">api</code> command into the server console. This will create a new file, "mcserver_api.lua", next to the MCS executable. Move that file into the "api/lua" subfolder inside your ZBS's folder.</p>
+ <p>After you download the mcserver.lua file and install the completion support, you need to restart ZBS in order for the plugin to load. If there are no errors, you should see two new items in the Project -> Lua Interpreter submenu: "MCServer - debug mode" and "MCServer - release mode". The only difference between the two is which filename they use to launch MCServer - mcserver_debug(.exe) for the debug option and "mcserver(.exe)" for the release option. If you built your own MCServer executable and you built it in debug mode, you should select the debug mode option. In all other cases, including if you downloaded the already-compiled MCServer executable from the internet, you should select the release mode option.</p>
+ <p>For a first time user, it might be a bit overwhelming that there are no GUI settings in the ZBS, yet the IDE is very configurable. There are two files that you edit in order to change settings, either system-wide (all users of the computer share those settings) or user-wide (the settings are only for a specific user of the computer). Those files are regular Lua sources and you can quickly locate them and edit them from within the IDE itself, select Edit -> Preferences -> Settings: XYZ from the menu, with XYZ being either System or User.</p>
+ <p>There is a documentation on most of the settings on ZBS's webpage, have a look at <a href="http://studio.zerobrane.com/documentation.html">http://studio.zerobrane.com/documentation.html</a>, especially the Preferences section. Personally I recommend setting editor.usetabs to true and possibly adjusting the editor.tabwidth, turn off the editor.smartindent feature and for debugging the option debugger.alloweditting should be set to true unless you feel like punishing yourself.</p>
+
+ <h2><img src="Static/zbs_logo.png" /> Project management</h2>
+ <p>ZBS works with projects, it considers all files and subfolder in a specific folder to be a project. There's no need for a special project file nor for adding individual files to the workspace, all files are added automatically. To open a MCS plugin as the project, click the triple-dot button in the Project pane, or select Project -> Project directory -> Choose... from the menu. Browse and select the MCS plugin's folder. ZBS will load all the files in the plugin's folder and you can start editting code.</p>
+ <p>Note that although ZBS allows you to work with subfolders in your plugins (and you should, especially with larger plugins), the current mcserver ZBS plugin will not be able to start debugging unless you have a file open in the editor that is at the root level of the MCS plugin's folder.</p>
+
+ <h2><img src="Static/zbs_logo.png" /> Debugging</h2>
+ <p>You are now ready to debug your code. Before doing that, though, don't forget to save your project files. If you haven't done so already, enable your plugin in the settings.ini file. If you want the program to break at a certain line, it is best to set the breakpoint before starting the program. Set the cursor on the line and hit F9 (or use menu Project -> Toggle Breakpoint) to toggle a breakpoint on that line. Finally, hit F5, or select menu Project -> Start Debugging to launch MCServer under the debugger. The MCServer window comes up and loads your plugin. If the window doesn't come up, inspect the Output pane in ZBS, there are usually two reasons for failure:<ul>
+ <li>Your code in the currently open file has a hard syntax error. These are reported as "Compilation error" in the Output pane, double-click the line to go to the error</li>
+ <li>ZBS cannot find the MCServer executable. Make sure you are editting a file two levels down the folder hierarchy from the MCS executable and that the MCS executable is named properly (mcserver[.exe] or mcserver_debug[.exe]). Also make sure you have selected the right Interpreter (menu Project -> Lua Interpreter).</li>
+ </ul></p>
+ <p>Once running, if the execution hits a breakpoint, the ZBS window will come up and a green arrow is displayed next to the breakpoint line. You can step through the code using F10 (Step Into) and Shift+F10 (Step Over). You can also use the Watch window to inspect variable values, or simply hover your mouse over a variable to display its value in the tooltip. Use the Remote console pane to execute commands directly *inside* the MCServer's plugin context.</p>
+ <p>You can also use the Project -> Break menu item to break into the debugger as soon as possible. You can also set breakpoints while the MCS plugin is running. Note that due to the way in which the debugger is implemented, MCS may execute some more Lua code before the break / breakpoint comes into effect. If MCS is not executing any Lua code in your plugin, it will not break until the plugin code kicks in again. This may result in missed breakpoints and delays before the Break command becomes effective. Therefore it's best to set breakpoints before running the program, or while the program is waiting in another breakpoint.</p>
+ </div>
+ </body>
+</html>
diff --git a/MCServer/Plugins/APIDump/Static/zbs_logo.png b/MCServer/Plugins/APIDump/Static/zbs_logo.png
new file mode 100644
index 000000000..c8d6d6278
--- /dev/null
+++ b/MCServer/Plugins/APIDump/Static/zbs_logo.png
Binary files differ
diff --git a/MCServer/Plugins/APIDump/Static/zbs_workspace.png b/MCServer/Plugins/APIDump/Static/zbs_workspace.png
new file mode 100644
index 000000000..9ce17e35a
--- /dev/null
+++ b/MCServer/Plugins/APIDump/Static/zbs_workspace.png
Binary files differ
diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua
index 7455c3cd2..52199740b 100644
--- a/MCServer/Plugins/APIDump/main_APIDump.lua
+++ b/MCServer/Plugins/APIDump/main_APIDump.lua
@@ -1408,9 +1408,9 @@ end
--- Dumps the entire API table into a file in the ZBS format
local function DumpAPIZBS(a_API)
LOG("Dumping ZBS API description...")
- local f, err = io.open("mcserver.lua", "w")
+ local f, err = io.open("mcserver_api.lua", "w")
if (f == nil) then
- LOG("Cannot open mcserver.lua for writing, ZBS API will not be dumped. " .. err)
+ LOG("Cannot open mcserver_lua.lua for writing, ZBS API will not be dumped. " .. err)
return
end
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-02 19:25:23 +0100