SphereWiki - User contributions [en]

Main Page

2023-08-03T17:35:46Z

Soulless:

<div style="background-color:#a7bcdc; color:#000; min-width:650px; padding:1px; text-align:center; width:100%;">
'''Starting with SphereServer'''
</div>
<div style="min-width:650px; width:100%;">
<div style="border-right:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:33%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Setup of Sphere'''
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Where to get Sphere]]
* [[Installing Sphere]]
* [[Configuring Sphere.ini]]
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Sphere 101'''
</div>
<div style="padding:0px 0px 5px 10px;">
* [[Chapter 1]] ''(Numbers, DEFNAME, ITEMDEF, CHARDEF)''
* [[Chapter 2]] ''(Sphere files explained)''
* [[Chapter 3]] ''(Scripting NPC's and items, Cool commands)''
* [[Chapter 4]] ''(Objects, operators, speech)''
* [[Chapter 5]] ''(Tags, Vars, Locals, Functions)''
* [[Chapter 6]] ''(LINKs, TIMERs, TARGETs)''
* [[Chapter 7]] ''(Loops and powerful functions)''
* [[Chapter 8]] ''(SKILLMENUs, MENUs, Gumps)''
* [[Chapter 9]] ''(Events)''
* [[Chapter 10]] ''(String Handling)''
</div>
</div>
<div style="border-left:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:67%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Extra Tutorials'''
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Common Mistakes|Common Mistakes Explained]] ''(A revision of Maximus's tutorial on the forums, and continuation of Taran's Misconceptions tutorial)''
* [[Internet and Sphere]] ''(And how to make the right use of them)''
* [[Languages Tutorial]] ''(How to script your own language system)''
* [[Making your own Skills]] ''(How to make and customize your skill)''
* [[Mul Patching Tutorial|Nazghul's Mul Patching Tutorial]] [http://sorea.profitux.cz/patching/ external link] ''(A document about mul patching and customizing your server)''
* [[Overriding Hardcoded Commands]] ''(How to override hardcoded commands and functions)''
* [[Scheduled Reboot]] ''(How to schedule system reboots)''
* [[Using MySQL]] ''(How to use MySQL)''
* [[Bitwise Operations]] ''(How to work with FLAGS/ATTR)''
* [[Script Debugging]] ''(How to fix your scripts)''
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''IMPORTANT LINKS'''
</div>
<div style="padding:0px 0px 5px 10px;">
* [https://github.com/Sphereserver SphereServer Official Github]
* [https://forum.spherecommunity.net/sshare.php?srt=4 Download Nightly Builds] ''(Plus! Extra downloads, like tools and scripts!)''
* [https://github.com/Sphereserver/Source-X/blob/master/Changelog.txt SphereX Changelog] | [https://github.com/Sphereserver/Source/blob/master/changelog.txt 56d Changelog] | [https://github.com/Sphereserver/Source-X/tree/master/docst Older Changelog]
* [https://discord.gg/BZj2fEA Join us at Discord] ''(We will solve most of your doubts over there)''
</div>
</div>
</div>
.

<div style="background-color:#a7bcdc; color:#000; min-width:650px; padding:1px; text-align:center; width:100%;">
'''Reference Compendium'''
</div>
<div style="min-width:650px; width:100%;">
<div style="border-right:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:33%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Definitions|'''Definitions''']]
</div>
<div style="padding:0px 0px 5px 10px;">
* [[CHARDEF|Characters]]
* [[DIALOG|Dialogs]]
* [[EVENTS|Events]]
* [[ITEMDEF|Items]]
* [[MENU|Menus]]
* [[REGIONRESOURCE|Region Resources]]
* [[REGIONTYPE|Region Types]]
* [[AREADEF|Regions]]
* [[ROOMDEF|Rooms]]
* [[SKILLCLASS|Skill Classes]]
* [[SKILLMENU|Skill Menus]]
* [[SKILL|Skills]]
* [[SPAWN|Spawn Groups]]
* [[SPELL|Spells]]
* [[TYPEDEF|Types]]
</div>
</div>
<div style="border-left:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:67%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Objects|'''Objects''']]
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Accounts]]
* [[Characters]]
* [[Database]]
* [[Files]]
* [[GM Pages]]
* [[Items]]
** ''[[Special Items]]''
* [[Map Points]]
* [[Parties]]
* [[Regions]]
* [[Rooms]]
* [[Sectors]]
* [[Server]]
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Scripts|'''Scripts''']]
</div>
<div style="padding:0px 0px 5px 10px;">
* [[:Category:Functions|Functions and Triggers]]
* [[:Category:Variables|General Functions, Properties and References]]
* [[Intrinsic Functions]]
* [[:Category:Statements|Statements]]
* [[:Category:Triggers|Triggers]]
</div>
</div>
.
----

.

==Useful Links==
* Modern SphereServer Nightly Downloads (Server) https://forum.spherecommunity.net/sshare.php?srt=4
* Older/Classic SphereServer downloads (Server) https://forum.spherecommunity.net/sshare.php?srt=4&prj=7
* Sphere-X Script Pack (Scripts) https://github.com/Sphereserver/Scripts-X
* Julians Script Vault (Scripts) https://github.com/JulianUO/SphereX-ScriptsVault
* List of UO Packets (Info) https://docs.polserver.com/packets/index.php
* Scripts https://mirror.ashkantra.de/scripts/Sphere/
* GM Commands (Commands) https://wiki.spherecommunity.net/index.php?title=GM_Commands
* Axis 2 Downloads (GM Tool) https://forum.spherecommunity.net/sshare.php?srt=4&prj=1
* Leviathan (GM tool) https://github.com/cbnolok/Leviathan/releases
* Ultima Online Downloads (Clients) https://mega.nz/folder/6uYxnIpY#tahGzzz_yOkLgNM1c_DxdQ
* Client 7.0.20 https://mirror.ashkantra.de/fullclients/
* ClassicUO (Third Party Client) https://www.classicuo.eu/
* OrionUO (Third Party Client) http://orionuo.online/
* CentrED (Worldbuilding) https://uo.wzk.cz/centred/
* UO-Pixel (Graphics) http://www.uo-pixel.de/
* UO Fiddler ( MUL Viewer) http://uofiddler.polserver.com/
* UO Grafiken by Nyray (Graphics) https://nyray.wordpress.com/
* Vestimisu (Graphics) http://vestimisu.blogspot.com/
* Ultima Online Graphics By Rubra (Graphcs) http://uographicsrubra.blogspot.com/
* Isis‘ UO Grafiken (Graphics) https://isispixel.wordpress.com/
* ServUO (Graphics) https://www.servuo.com/archive/categories/assets.13/
* UOGateway (Shard Listing) https://uogateway.com/

==Sphere 3rd Party Tools==
* [http://forum.spherecommunity.net/sshare.php?srt=4&uid=603 Axis II] - GM Tool for Sphere that will allow you to place objects in-game, spawns, traveling and many other useful functions for shard admins and GMs.
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=3 vSCP] - vSCP is the most complete and up-to-date syntax editor for sphere scripting. It does contain syntax highlighting, autocomplete, folding markers to specify blocks of code that can expand or collapse, bookmarks, autoindent, find/replace/gotoline, help guide for all the sphere elements added to your code, and more!
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=2 vServerLauncher] - Install and run the latest build of sphereserver in a few clicks with vServerLauncher. It's pretty quick and simple!
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=5 SphereService] - Relaunch SphereSvr.exe everytime it closes/crashes. Automatically runs at windows startup and works in a silent mode minimized to Tray.
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=4 vCrypter] - Type the client version and the tool will calculate the correct UO login keys for classic or enhanced clients.

==Other Articles==

* [[Armor Calculation]]
* [[Client Changes]]
* [[Common Scripting Misconceptions]]
* [[Custom Object Properties]]
* [[Error Codes]]
* [[Experience System]]
* [[How Combat Works]]
* [[Occam's Razor]]
* [[Optimization|Optimization Theory]]
* [[Override TAGs]]
* [[Revisions Changelog]]
* [[Sendpacket]]
* [[Skill Gain Theory]]
* [[The Process of Scripting]]
* [[Building Component Reference]]

==Credits==

'''Special thanks to:'''

[[WhoIsWho|XuN, Nolok, Ben, and Drk]], for their hard work on the X branch taking Sphere into the next decade.

[[WhoIsWho|Ben, Cloud_Br, Ellessar, Jdog, Lord Zerofiz, Mordaunt, Nazghul-ll, RanXerox, Rattlehead, Sandman, Sharlenwar, ShiryuX, thelegbra, Maximus, WarAngel and Valios]], for helping to add content.

[[WhoIsWho|Daleth]], for writing the Sphere Reference Project, and [[WhoIsWho|Mordaunt]] for converting it to .chm format.

[[WhoIsWho|Tracker]], for writing the Sphere 56 Tracking Changes in Sphereserver.net

[[WhoIsWho|Taran]], for writing the original and now famous Sphere Scripting for Dummies tutorials, and [[WhoIsWho|MrSugarCube]] for bringing it up-to-date directly from source.

[[WhoIsWho|Ben, Khaos, Ranxerox, Shiryux, Furio, Radiant, Vjaka, Nazghul-ll, Ellessar, Torfo, Shadow Dragon, MrSugarCube and coruja747]] for continuing to develop Sphere into a powerful and very customizable Ultima Online emulator.

[[WhoIsWho|Crius]], for providing hosting for the original SphereWiki, and [[WhoIsWho|Torfo]] for providing the current hosting.

==External Links==

* [[Useful Links]] ''(An ongoing list of useful links for community members)''
* [http://www.spherecommunity.net/ Official SphereServer Website]
* [https://forum.spherecommunity.net/sshare.php?srt=4 Nightly builds]
* [http://nightly.prerelease.sphere.torfo.org/ Nightly builds - OUTDATED, use the link above]
* [http://spherepack.codeplex.com/ Sphere Community Pack 2.0]
* [http://uo.torfo.org/packetguide/ Jerrith's UO Packet Guide]
* [http://uo.torfo.org/packetguideKR/ Wyatt&Kons's UOKR Packet Guide]

[[Category: Navigation]]

Error Codes

2023-07-01T17:04:44Z

Soulless: /* Exit Codes */

{{Languages|Error_Codes}}

__FORCETOC__
==Exit Codes==
When Sphere closes, an 'exit code' will normally be shown in the console to describe why it is being shut down. In general, an exit code less than 0 is considered to be an error code, and values above 0 are normal shutdown codes. In most cases, a more descriptive error will be shown in the console and/or log file to help better diagnose the reason behind error codes.

The following table lists all of the current codes and their meanings.

{| border="1" cellpadding="3"
| '''Code''' || '''Description'''
|-
| -10 || Unexpected error occurred
|-
| -9 || Failed to bind server port
|-
| -8 || Failed to load world save(s)
|-
| -3 || Failed to load server settings (script, ini, mul files) ''or'' <br />did not write AGREE=1 in the sphere.ini
|-
| -1 || Shutdown via commandline (/?, /T and /Q switches)
|-
| 1 || X in console ''or'' <br />SIGHUP signal, terminal closed (Linux Only)
|-
| 2 || SHUTDOWN command
|-
| 4 || Service shutdown ''(Windows Only)''
|-
| 5 || Console window closed ''(Windows Only)''
|-
| 6 || SIGABRT signal, process aborted ''(Linux Only)''
|}

==Garbage Collection==
The purpose of garbage collection is to validate all of the server objects and free up unused UIDs. Garbage collection is initiated:
* After the world save is loaded at startup.
* Before a world save begins, if the [[FORCEGARBAGECOLLECT]] setting is enabled in Sphere.ini.
* After the [[IMPORT]] or [[RESTORE]] functions have been used on the [[Server|server]] object.
* When the 'G' command is entered via the Sphere console
* When the [[GARBAGE]] function is used on the [[Server|server]] object.

When garbage collection encounters a problem with an object it may attempt to automatically correct the error, otherwise the object will be removed. When an object is removed by garbage collection there will normally be an error shown in the console describing the item that was removed along with the reason. The following table lists all of the garbage collection codes along with their description:

{| border="1" cellpadding="3"
| '''Code''' || '''Message''' || '''Description''' ||
|-
| 1102 || Disconnected charr not acting as such || A character has been marked disconnected from the world, but it is not listed in the sector's disconnected character's list. || *
|-
| 1103 || Ridden NPC not acting as such || An NPC has the [[FLAGS|statf_ridden]] flag set, but does not have its [[ACTION]] property set to 111. ||
|-
| 1104 || Ridden NPC without a mount item || An NPC has the [[FLAGS|statf_ridden]] flag set, but its [[ACTARG1]] property isn't set to the [[UID]] of an item whose [[TYPE]] property is set to [[TYPE|t_figurine]] or [[TYPE|t_eq_horse]]. ||
|-
| 1105 || Ridden NPC with a mislinked mount item || An NPC has the [[FLAGS|statf_ridden]] flag set, but its [[ACTARG1]] property isn't set to the [[UID]] of an item whose [[MORE2]] property matches the NPC's [[UID]]. ||
|-
| 1106 || Disconnected NPC neither dead nor ridden || An NPC has been disconnected from the world, but does not have either one of the [[FLAGS|statf_ridden]] or [[FLAGS|statf_dead]] flags set. ||
|-
| 1107 || In game char that is neither a player nor an NPC || A character is not a player or an NPC. || *
|-
| 1108 || Char not on a valid position || A character's [[P|position]] is outside of the map boundaries. ||
|-
| 1203 || Ridden NPC not acting as such || Same as 1103. ||
|-
| 1204 || Ridden NPC without a mount item || Same as 1104. ||
|-
| 1205 || In game char that is neither a player nor an NPC || Same as 1107. ||
|-
| 2102 || Item without ITEMDEF || An item does not have an [[ITEMDEF]] section. || *
|-
| 2103 || Item ITEMDEF with ID = 0 || An item's [[ITEMDEF]] has an [[ID]] of zero. || *
|-
| 2104 || Disconnected item || An item has been marked as disconnected from the world. || *
|-
| 2105 || Item not on a valid position || An item is not in a container and its [[P|position]] is outside of the map boundaries. ||
|-
| 2106 || Item flagged as being in a container but it isn't || An item is flagged as not being top level, but it does not have a container. ||
|-
| 2202 || Item flagged as equipped but it isn't || An item is flagged as being equipped, but its parent is not a character. ||
|-
| 2205 || Mislinked item || An item's [[LINK]] property matches its [[UID]], or has been set to a [[UID]] that doesn't exist. ||
|-
| 2206 || Gm Robe / Deathshroud not on a char || A GM robe or death shroud ([[ID]] of 0204E or 0204F) is not equipped to a character. ||
|-
| 2207 || Deathshroud not on a dead char || A death shroud ([[ID]] of 0204F) is equipped to a character without the [[FLAGS|statf_dead]] flag set. ||
|-
| 2208 || Gm Robe on a char without privilege || A GM robe ([[ID]] of 0204E) is equipped to a character whose [[PLEVEL]] is less than 2. ||
|-
| 2220 || Trade window memory not equipped in the correct layer || A [[TYPE|t_eq_trade window]] item type is not equipped, has its [[LAYER]] property set to something other than [[LAYER|layer_none]], or is equipped to an NPC. ||
|-
| 2221 || Client linger memory not equipped in the correct layer || A [[TYPE|t_eq_client_linger]] item type is not equipped, has its [[LAYER]] property set to something other than [[LAYER|layer_flag_clientlinger]], or is equipped to an NPC. ||
|-
| 2222 || Memory not equipped / not in the memory layer / without color || A memory item ([[ID]] of 02007) is not equipped, or a non-memory item has had its [[TYPE]] set to [[TYPE|t_eq_memory_obj]] after creation. ||
|-
| 2226 || Mount memory not equipped in the correct layer || A [[TYPE|t_eq_horse]] item type is not equipped, or has its [[LAYER]] property set to something other than [[LAYER|layer_horse]]. ||
|-
| 2227 || Hair/Beard item not equipped / not in a corpse / not in a vendor box || A [[TYPE|t_hair]] or [[TYPE|t_beard]] item type that isn't equipped, is either not in a container or its container has an [[ID]] other than 02006 or 02AF8. ||
|-
| 2228 || Hair/Beard item not equipped / not in a corpse / not in a vendor box || A [[TYPE|t_hair]] or [[TYPE|t_beard]] item is equipped, but has its [[LAYER]] property set to something other than [[LAYER|layer_hair]] or [[LAYER|layer_beard]]. ||
|-
| 2229 || Game piece not in a game board || A [[TYPE|t_game_piece]] item has been found outside of a container. ||
|-
| 2230 || Item equipped in the trade window layer but it isn't a trade window || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_none]], but its [[TYPE|type]] is not [[TYPE|t_eq_trade_window]]. ||
|-
| 2231 || Item equipped in the memory layer but it isn't a memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_special]], but its [[TYPE|type]] is not [[TYPE|t_eq_memory_obj]] or [[TYPE|t_eq_script]]. ||
|-
| 2233 || Item equipped in the mount memory layer but it isn't a mount memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_horse]], but its [[TYPE|type]] is not [[TYPE|t_eq_horse]]. ||
|-
| 2234 || Item equipped in the client linger layer but it isn't a client linger memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_flag_clientlinger]], but its [[TYPE|type]] is not [[TYPE|t_eq_client_linger]]. ||
|-
| 2235 || Item equipped in the murder memory layer but it isn't a murder memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_flag_murders]], but the character is an NPC or the player has its [[KILLS]] property set to 0. ||
|-
| 2236 || Item flagged as decay but without timer set || A top-level item has the [[ATTR|attr_decay]] flag set, but its [[TIMER]] property has not been set. ||
|-
| 3101 || Object is totaly lost, no parent exists || An object has no parent. || *
|-
| 3102 || Object was deleted or UID is incorrect || An object does not have a valid [[UID]]. || *
|-
| 3201 || Object not correctly loaded by server (UID conflict) || More than one object has the same [[UID]] value. || *
|-
| 4222 || Memory not equipped / not in the memory layer / without color || A memory item is not flagged as equipped, has its [[LAYER]] property set to something other than [[LAYER|layer_special]], or has its [[COLOR]] property set to 0. ||
|-
| 4223 || Memory not on a char || A memory item is flagged as equipped, but it's [[CONT|parent]] is not a character. ||
|-
| 4224 || Stone/Guild memory mislinked || A memory item's [[COLOR]] property has one of the [[COLOR|memory_guild]] or [[COLOR|memory_town]] flags set, but the [[LINK]] property is not set to the [[UID]] of a guild or town stone. ||
|-
| 4225 || Stone/Guild memory linked to the wrong stone || A memory item's [[COLOR]] property has one of the [[COLOR|memory_guild]] or [[COLOR|memory_town]] flags set, but the character the memory is equipped to is not a member of the guild or town. ||
|-
| 7101 || Object's UID does not match up with server's UID table. || An object does not have the expected [[UID]] value. || *
|-
| 7102 || Object does not exist. || An object does not exist. || *
|-
| FFFF || Bad memory allocation || An exception was thrown whilst checking the object's validity. || *
|}

'''Note''': ''Garbage collection codes marked with * generally indicate a serious error within an object's internal state and should not normally be seen. If you are experiencing and are able to reliably reproduce any such errors then please report the details to the [http://tracker.sphere.torfo.org/bugs/main_page.php bug tracker].''

Error Codes

2023-07-01T17:04:24Z

Soulless: /* Exit Codes */

{{Languages|Error_Codes}}

__FORCETOC__
==Exit Codes==
When Sphere closes, an 'exit code' will normally be shown in the console to describe why it is being shut down. In general, an exit code less than 0 is considered to be an error code, and values above 0 are normal shutdown codes. In most cases, a more descriptive error will be shown in the console and/or log file to help better diagnose the reason behind error codes.

The following table lists all of the current codes and their meanings.

{| border="1" cellpadding="3"
| '''Code''' || '''Description'''
|-
| -10 || Unexpected error occurred
|-
| -9 || Failed to bind server port
|-
| -8 || Failed to load world save(s)
|-
| -3 || Failed to load server settings (script, ini, mul files) ''or'' did not write AGREE=1 in the sphere.ini
|-
| -1 || Shutdown via commandline (/?, /T and /Q switches)
|-
| 1 || X in console ''or'' <br />SIGHUP signal, terminal closed (Linux Only)
|-
| 2 || SHUTDOWN command
|-
| 4 || Service shutdown ''(Windows Only)''
|-
| 5 || Console window closed ''(Windows Only)''
|-
| 6 || SIGABRT signal, process aborted ''(Linux Only)''
|}

==Garbage Collection==
The purpose of garbage collection is to validate all of the server objects and free up unused UIDs. Garbage collection is initiated:
* After the world save is loaded at startup.
* Before a world save begins, if the [[FORCEGARBAGECOLLECT]] setting is enabled in Sphere.ini.
* After the [[IMPORT]] or [[RESTORE]] functions have been used on the [[Server|server]] object.
* When the 'G' command is entered via the Sphere console
* When the [[GARBAGE]] function is used on the [[Server|server]] object.

When garbage collection encounters a problem with an object it may attempt to automatically correct the error, otherwise the object will be removed. When an object is removed by garbage collection there will normally be an error shown in the console describing the item that was removed along with the reason. The following table lists all of the garbage collection codes along with their description:

{| border="1" cellpadding="3"
| '''Code''' || '''Message''' || '''Description''' ||
|-
| 1102 || Disconnected charr not acting as such || A character has been marked disconnected from the world, but it is not listed in the sector's disconnected character's list. || *
|-
| 1103 || Ridden NPC not acting as such || An NPC has the [[FLAGS|statf_ridden]] flag set, but does not have its [[ACTION]] property set to 111. ||
|-
| 1104 || Ridden NPC without a mount item || An NPC has the [[FLAGS|statf_ridden]] flag set, but its [[ACTARG1]] property isn't set to the [[UID]] of an item whose [[TYPE]] property is set to [[TYPE|t_figurine]] or [[TYPE|t_eq_horse]]. ||
|-
| 1105 || Ridden NPC with a mislinked mount item || An NPC has the [[FLAGS|statf_ridden]] flag set, but its [[ACTARG1]] property isn't set to the [[UID]] of an item whose [[MORE2]] property matches the NPC's [[UID]]. ||
|-
| 1106 || Disconnected NPC neither dead nor ridden || An NPC has been disconnected from the world, but does not have either one of the [[FLAGS|statf_ridden]] or [[FLAGS|statf_dead]] flags set. ||
|-
| 1107 || In game char that is neither a player nor an NPC || A character is not a player or an NPC. || *
|-
| 1108 || Char not on a valid position || A character's [[P|position]] is outside of the map boundaries. ||
|-
| 1203 || Ridden NPC not acting as such || Same as 1103. ||
|-
| 1204 || Ridden NPC without a mount item || Same as 1104. ||
|-
| 1205 || In game char that is neither a player nor an NPC || Same as 1107. ||
|-
| 2102 || Item without ITEMDEF || An item does not have an [[ITEMDEF]] section. || *
|-
| 2103 || Item ITEMDEF with ID = 0 || An item's [[ITEMDEF]] has an [[ID]] of zero. || *
|-
| 2104 || Disconnected item || An item has been marked as disconnected from the world. || *
|-
| 2105 || Item not on a valid position || An item is not in a container and its [[P|position]] is outside of the map boundaries. ||
|-
| 2106 || Item flagged as being in a container but it isn't || An item is flagged as not being top level, but it does not have a container. ||
|-
| 2202 || Item flagged as equipped but it isn't || An item is flagged as being equipped, but its parent is not a character. ||
|-
| 2205 || Mislinked item || An item's [[LINK]] property matches its [[UID]], or has been set to a [[UID]] that doesn't exist. ||
|-
| 2206 || Gm Robe / Deathshroud not on a char || A GM robe or death shroud ([[ID]] of 0204E or 0204F) is not equipped to a character. ||
|-
| 2207 || Deathshroud not on a dead char || A death shroud ([[ID]] of 0204F) is equipped to a character without the [[FLAGS|statf_dead]] flag set. ||
|-
| 2208 || Gm Robe on a char without privilege || A GM robe ([[ID]] of 0204E) is equipped to a character whose [[PLEVEL]] is less than 2. ||
|-
| 2220 || Trade window memory not equipped in the correct layer || A [[TYPE|t_eq_trade window]] item type is not equipped, has its [[LAYER]] property set to something other than [[LAYER|layer_none]], or is equipped to an NPC. ||
|-
| 2221 || Client linger memory not equipped in the correct layer || A [[TYPE|t_eq_client_linger]] item type is not equipped, has its [[LAYER]] property set to something other than [[LAYER|layer_flag_clientlinger]], or is equipped to an NPC. ||
|-
| 2222 || Memory not equipped / not in the memory layer / without color || A memory item ([[ID]] of 02007) is not equipped, or a non-memory item has had its [[TYPE]] set to [[TYPE|t_eq_memory_obj]] after creation. ||
|-
| 2226 || Mount memory not equipped in the correct layer || A [[TYPE|t_eq_horse]] item type is not equipped, or has its [[LAYER]] property set to something other than [[LAYER|layer_horse]]. ||
|-
| 2227 || Hair/Beard item not equipped / not in a corpse / not in a vendor box || A [[TYPE|t_hair]] or [[TYPE|t_beard]] item type that isn't equipped, is either not in a container or its container has an [[ID]] other than 02006 or 02AF8. ||
|-
| 2228 || Hair/Beard item not equipped / not in a corpse / not in a vendor box || A [[TYPE|t_hair]] or [[TYPE|t_beard]] item is equipped, but has its [[LAYER]] property set to something other than [[LAYER|layer_hair]] or [[LAYER|layer_beard]]. ||
|-
| 2229 || Game piece not in a game board || A [[TYPE|t_game_piece]] item has been found outside of a container. ||
|-
| 2230 || Item equipped in the trade window layer but it isn't a trade window || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_none]], but its [[TYPE|type]] is not [[TYPE|t_eq_trade_window]]. ||
|-
| 2231 || Item equipped in the memory layer but it isn't a memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_special]], but its [[TYPE|type]] is not [[TYPE|t_eq_memory_obj]] or [[TYPE|t_eq_script]]. ||
|-
| 2233 || Item equipped in the mount memory layer but it isn't a mount memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_horse]], but its [[TYPE|type]] is not [[TYPE|t_eq_horse]]. ||
|-
| 2234 || Item equipped in the client linger layer but it isn't a client linger memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_flag_clientlinger]], but its [[TYPE|type]] is not [[TYPE|t_eq_client_linger]]. ||
|-
| 2235 || Item equipped in the murder memory layer but it isn't a murder memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_flag_murders]], but the character is an NPC or the player has its [[KILLS]] property set to 0. ||
|-
| 2236 || Item flagged as decay but without timer set || A top-level item has the [[ATTR|attr_decay]] flag set, but its [[TIMER]] property has not been set. ||
|-
| 3101 || Object is totaly lost, no parent exists || An object has no parent. || *
|-
| 3102 || Object was deleted or UID is incorrect || An object does not have a valid [[UID]]. || *
|-
| 3201 || Object not correctly loaded by server (UID conflict) || More than one object has the same [[UID]] value. || *
|-
| 4222 || Memory not equipped / not in the memory layer / without color || A memory item is not flagged as equipped, has its [[LAYER]] property set to something other than [[LAYER|layer_special]], or has its [[COLOR]] property set to 0. ||
|-
| 4223 || Memory not on a char || A memory item is flagged as equipped, but it's [[CONT|parent]] is not a character. ||
|-
| 4224 || Stone/Guild memory mislinked || A memory item's [[COLOR]] property has one of the [[COLOR|memory_guild]] or [[COLOR|memory_town]] flags set, but the [[LINK]] property is not set to the [[UID]] of a guild or town stone. ||
|-
| 4225 || Stone/Guild memory linked to the wrong stone || A memory item's [[COLOR]] property has one of the [[COLOR|memory_guild]] or [[COLOR|memory_town]] flags set, but the character the memory is equipped to is not a member of the guild or town. ||
|-
| 7101 || Object's UID does not match up with server's UID table. || An object does not have the expected [[UID]] value. || *
|-
| 7102 || Object does not exist. || An object does not exist. || *
|-
| FFFF || Bad memory allocation || An exception was thrown whilst checking the object's validity. || *
|}

'''Note''': ''Garbage collection codes marked with * generally indicate a serious error within an object's internal state and should not normally be seen. If you are experiencing and are able to reliably reproduce any such errors then please report the details to the [http://tracker.sphere.torfo.org/bugs/main_page.php bug tracker].''

Error Codes

2023-07-01T17:04:08Z

Soulless: /* Exit Codes */

{{Languages|Error_Codes}}

__FORCETOC__
==Exit Codes==
When Sphere closes, an 'exit code' will normally be shown in the console to describe why it is being shut down. In general, an exit code less than 0 is considered to be an error code, and values above 0 are normal shutdown codes. In most cases, a more descriptive error will be shown in the console and/or log file to help better diagnose the reason behind error codes.

The following table lists all of the current codes and their meanings.

{| border="1" cellpadding="3"
| '''Code''' || '''Description'''
|-
| -10 || Unexpected error occurred
|-
| -9 || Failed to bind server port
|-
| -8 || Failed to load world save(s)
|-
| -3 || Failed to load server settings (script, ini, mul files) Or did not write AGREE=1 in the sphere.ini
|-
| -1 || Shutdown via commandline (/?, /T and /Q switches)
|-
| 1 || X in console ''or'' <br />SIGHUP signal, terminal closed (Linux Only)
|-
| 2 || SHUTDOWN command
|-
| 4 || Service shutdown ''(Windows Only)''
|-
| 5 || Console window closed ''(Windows Only)''
|-
| 6 || SIGABRT signal, process aborted ''(Linux Only)''
|}

==Garbage Collection==
The purpose of garbage collection is to validate all of the server objects and free up unused UIDs. Garbage collection is initiated:
* After the world save is loaded at startup.
* Before a world save begins, if the [[FORCEGARBAGECOLLECT]] setting is enabled in Sphere.ini.
* After the [[IMPORT]] or [[RESTORE]] functions have been used on the [[Server|server]] object.
* When the 'G' command is entered via the Sphere console
* When the [[GARBAGE]] function is used on the [[Server|server]] object.

When garbage collection encounters a problem with an object it may attempt to automatically correct the error, otherwise the object will be removed. When an object is removed by garbage collection there will normally be an error shown in the console describing the item that was removed along with the reason. The following table lists all of the garbage collection codes along with their description:

{| border="1" cellpadding="3"
| '''Code''' || '''Message''' || '''Description''' ||
|-
| 1102 || Disconnected charr not acting as such || A character has been marked disconnected from the world, but it is not listed in the sector's disconnected character's list. || *
|-
| 1103 || Ridden NPC not acting as such || An NPC has the [[FLAGS|statf_ridden]] flag set, but does not have its [[ACTION]] property set to 111. ||
|-
| 1104 || Ridden NPC without a mount item || An NPC has the [[FLAGS|statf_ridden]] flag set, but its [[ACTARG1]] property isn't set to the [[UID]] of an item whose [[TYPE]] property is set to [[TYPE|t_figurine]] or [[TYPE|t_eq_horse]]. ||
|-
| 1105 || Ridden NPC with a mislinked mount item || An NPC has the [[FLAGS|statf_ridden]] flag set, but its [[ACTARG1]] property isn't set to the [[UID]] of an item whose [[MORE2]] property matches the NPC's [[UID]]. ||
|-
| 1106 || Disconnected NPC neither dead nor ridden || An NPC has been disconnected from the world, but does not have either one of the [[FLAGS|statf_ridden]] or [[FLAGS|statf_dead]] flags set. ||
|-
| 1107 || In game char that is neither a player nor an NPC || A character is not a player or an NPC. || *
|-
| 1108 || Char not on a valid position || A character's [[P|position]] is outside of the map boundaries. ||
|-
| 1203 || Ridden NPC not acting as such || Same as 1103. ||
|-
| 1204 || Ridden NPC without a mount item || Same as 1104. ||
|-
| 1205 || In game char that is neither a player nor an NPC || Same as 1107. ||
|-
| 2102 || Item without ITEMDEF || An item does not have an [[ITEMDEF]] section. || *
|-
| 2103 || Item ITEMDEF with ID = 0 || An item's [[ITEMDEF]] has an [[ID]] of zero. || *
|-
| 2104 || Disconnected item || An item has been marked as disconnected from the world. || *
|-
| 2105 || Item not on a valid position || An item is not in a container and its [[P|position]] is outside of the map boundaries. ||
|-
| 2106 || Item flagged as being in a container but it isn't || An item is flagged as not being top level, but it does not have a container. ||
|-
| 2202 || Item flagged as equipped but it isn't || An item is flagged as being equipped, but its parent is not a character. ||
|-
| 2205 || Mislinked item || An item's [[LINK]] property matches its [[UID]], or has been set to a [[UID]] that doesn't exist. ||
|-
| 2206 || Gm Robe / Deathshroud not on a char || A GM robe or death shroud ([[ID]] of 0204E or 0204F) is not equipped to a character. ||
|-
| 2207 || Deathshroud not on a dead char || A death shroud ([[ID]] of 0204F) is equipped to a character without the [[FLAGS|statf_dead]] flag set. ||
|-
| 2208 || Gm Robe on a char without privilege || A GM robe ([[ID]] of 0204E) is equipped to a character whose [[PLEVEL]] is less than 2. ||
|-
| 2220 || Trade window memory not equipped in the correct layer || A [[TYPE|t_eq_trade window]] item type is not equipped, has its [[LAYER]] property set to something other than [[LAYER|layer_none]], or is equipped to an NPC. ||
|-
| 2221 || Client linger memory not equipped in the correct layer || A [[TYPE|t_eq_client_linger]] item type is not equipped, has its [[LAYER]] property set to something other than [[LAYER|layer_flag_clientlinger]], or is equipped to an NPC. ||
|-
| 2222 || Memory not equipped / not in the memory layer / without color || A memory item ([[ID]] of 02007) is not equipped, or a non-memory item has had its [[TYPE]] set to [[TYPE|t_eq_memory_obj]] after creation. ||
|-
| 2226 || Mount memory not equipped in the correct layer || A [[TYPE|t_eq_horse]] item type is not equipped, or has its [[LAYER]] property set to something other than [[LAYER|layer_horse]]. ||
|-
| 2227 || Hair/Beard item not equipped / not in a corpse / not in a vendor box || A [[TYPE|t_hair]] or [[TYPE|t_beard]] item type that isn't equipped, is either not in a container or its container has an [[ID]] other than 02006 or 02AF8. ||
|-
| 2228 || Hair/Beard item not equipped / not in a corpse / not in a vendor box || A [[TYPE|t_hair]] or [[TYPE|t_beard]] item is equipped, but has its [[LAYER]] property set to something other than [[LAYER|layer_hair]] or [[LAYER|layer_beard]]. ||
|-
| 2229 || Game piece not in a game board || A [[TYPE|t_game_piece]] item has been found outside of a container. ||
|-
| 2230 || Item equipped in the trade window layer but it isn't a trade window || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_none]], but its [[TYPE|type]] is not [[TYPE|t_eq_trade_window]]. ||
|-
| 2231 || Item equipped in the memory layer but it isn't a memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_special]], but its [[TYPE|type]] is not [[TYPE|t_eq_memory_obj]] or [[TYPE|t_eq_script]]. ||
|-
| 2233 || Item equipped in the mount memory layer but it isn't a mount memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_horse]], but its [[TYPE|type]] is not [[TYPE|t_eq_horse]]. ||
|-
| 2234 || Item equipped in the client linger layer but it isn't a client linger memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_flag_clientlinger]], but its [[TYPE|type]] is not [[TYPE|t_eq_client_linger]]. ||
|-
| 2235 || Item equipped in the murder memory layer but it isn't a murder memory || An equipped item has been found with its [[LAYER]] property set to [[LAYER|layer_flag_murders]], but the character is an NPC or the player has its [[KILLS]] property set to 0. ||
|-
| 2236 || Item flagged as decay but without timer set || A top-level item has the [[ATTR|attr_decay]] flag set, but its [[TIMER]] property has not been set. ||
|-
| 3101 || Object is totaly lost, no parent exists || An object has no parent. || *
|-
| 3102 || Object was deleted or UID is incorrect || An object does not have a valid [[UID]]. || *
|-
| 3201 || Object not correctly loaded by server (UID conflict) || More than one object has the same [[UID]] value. || *
|-
| 4222 || Memory not equipped / not in the memory layer / without color || A memory item is not flagged as equipped, has its [[LAYER]] property set to something other than [[LAYER|layer_special]], or has its [[COLOR]] property set to 0. ||
|-
| 4223 || Memory not on a char || A memory item is flagged as equipped, but it's [[CONT|parent]] is not a character. ||
|-
| 4224 || Stone/Guild memory mislinked || A memory item's [[COLOR]] property has one of the [[COLOR|memory_guild]] or [[COLOR|memory_town]] flags set, but the [[LINK]] property is not set to the [[UID]] of a guild or town stone. ||
|-
| 4225 || Stone/Guild memory linked to the wrong stone || A memory item's [[COLOR]] property has one of the [[COLOR|memory_guild]] or [[COLOR|memory_town]] flags set, but the character the memory is equipped to is not a member of the guild or town. ||
|-
| 7101 || Object's UID does not match up with server's UID table. || An object does not have the expected [[UID]] value. || *
|-
| 7102 || Object does not exist. || An object does not exist. || *
|-
| FFFF || Bad memory allocation || An exception was thrown whilst checking the object's validity. || *
|}

'''Note''': ''Garbage collection codes marked with * generally indicate a serious error within an object's internal state and should not normally be seen. If you are experiencing and are able to reliably reproduce any such errors then please report the details to the [http://tracker.sphere.torfo.org/bugs/main_page.php bug tracker].''

Chapter 7

2023-02-09T18:07:33Z

Soulless: /* MAP */

{{Languages|Chapter_7}}

==Recursive Functions==
I discovered this very seldom explored extension of SPHERE scripting while reading messages on the boards. Someone was trying to create a function that counted the number of items in a container using this sort of thing, and it worked for the most part. I was very amazed, because before that, no one had even thought of using functions that looped back upon themselves.

Which is what a recursive function is. I'll say it one more time.

A recursive function is one that calls itself, or recurs. Surprise!

So how do we do this? It's as simple as calling a function:

<spherescript>[FUNCTION recursive_test]
recursive_test</spherescript>

This very small piece of code in fact IS a recursive function. As you can see, the function will call itself and start over from the beginning, which will proceed to call the function again, and again, and again, and on and on. In this case, we don't have any way to stop it. This is called an infinite loop, one that will continue forever without stopping. Your server will die a flaming death.

'''Lesson 1: How to NOT create an infinite loop'''

Let me tell you right now. You will write a script that implements an infinite loop. You will test it. Your server will die. It's guaranteed. No programmer can say that they have never accidentally written an infinite loop. (RANDOM NOTE: All windows programs are in fact infinite loops. Your SPHERE server is an infinite loop.) In a SPHERE script, however, here's what happens:

# The function is called.
# Some stuff takes place
# The function is called from within itself. Being a good scripting language, it records where it left off so it can go back later. This is called the stack.
# Go back to number 1.

This "stack" builds up very very quickly, and soon the server cannot allocate any more memory for it, and will crash when it tries. Fun stuff, I tell you.

Anyways, here is one way to avoid creating an infinite loop. Let's say we want to make a function that executes SRC.SYSMESSAGE Hello World 35 times. Here would be an example of how one could do this:

<spherescript>[FUNCTION recurse_hello]
IF (<ARGN1> < 1)
RETURN 1
ENDIF
SYSMESSAGE Hello World
RECURSE_HELLO <EVAL <ARGN1> - 1>
RETURN 1</spherescript>

Then, in another script, we would execute this command: <font color="darkred">SRC.RECURSE_HELLO 35</font>

Remember what ARGN is from the previous chapter? It's the argument to the function stored as a number. Initially, as you can see, it's 25 because we made it be that way. However, every time the function calls itself, or "recurses", it sets ARGN1 to be one less than itself. Here's the step-by-step analysis of this:

# The function is called. ARGN1 is 35 because we said so.
# It checks to see if ARGN1 is less than one. If it is, we immediately RETURN 1 and set off the chain reaction that stops the recursive function.
# The next part should be fairly obvious. We're sending a SYSMESSAGE to the default object. Because we used SRC when we initially called the function, the default object is SRC.
# This is where the recursion takes place. The function calls itself with an argument ONE LESS than the current one. This starts the whole thing over at step 1. This is a NEW FUNCTION CALL, remember. The original function call STILL EXISTS and the program will "rewind" back down the stack to that location later. That is why I have a RETURN 1 after the function call.

That's your example of a recursive function. It isn't very practical. Let's look at a more practical example. See if you can figure it out for yourself. This is courtesy of Belgar, for the most part:

<spherescript>[FUNCTION pack_to_bank]
IF (<FINDLAYER.21.FINDCONT.0.UID> == 0)
RETURN 1
ENDIF
FINDLAYER.21.FINDCONT.0.CONT = <FINDLAYER.layer_bankbox.UID>
PACK_TO_BANK
RETURN 1</spherescript>

(As you can see, we don't always need an ARGS to make a function loop. In this case, we use a backpack with an unknown number of items inside and only stop when the pack no longer contains items.)

Recursive functions are very useful. Be sure you don't overuse them, though! Remember, while a script is running, YOUR SERVER IS FROZEN. If a recursive function takes too long to complete, your server will lag. A good method is to make sure that no function should be looping more than about 500 times. (Actually other server emulators such as POL have a mechanism to catch "runaway scripts" like this and halt them in their tracks.)

==FOR==

===FOR===
FOR is a powerful way to create a recursive function, and it allows a simpler level of control over your recursions.

Usage:

<spherescript>[FUNCTION for_display]
FOR X 1 20
SYSMESSAGE <LOCAL.X> //Will sysmessage the current for count.
ENDFOR</spherescript>

The loop will loop through 20 times, starting at 1 and ending at 20. X is the variable containing the current FOR count. If no variable is declared, the count can be accessed using <LOCAL._FOR>

Changing LOCAL._FOR or whatever you declared as count, will not change the loop's behaviour. But be aware that if you "stack" FOR loops without giving them different loop variables, the innermost loop will overwrite the loop variables of its successors, usually leading towards a completely messup of the whole loop stuff.

===FORCHARLAYER===
FORCHARLAYER is another type of FOR loop. Basically it allows you to loop through each item that is stored on the specified layer of a character. This can be useful for when you want to manipulate all of the spell runes or memory items on a character as an alternative to using FINDLAYER.x in a loop.

Something to be aware of here is that whilst inside the loop, the default object will be temporarily changed to the item in the loop. As you can see in the following example, we must store a reference to the original default object (the character) so that we can still reference it from within the loop:

<spherescript>[FUNCTION get_mitems_names]
REF1 = <UID> // store the default object in REF1
FORCHARLAYER 30
REF1.SYSMESSAGE <NAME> is a memory item in layer <LAYER>
ENDFOR</spherescript>

===FORCHARMEMORYTYPE===
FORCHARMEMORYTYPE is a very useful type of FOR loop. You may want to use it for experience systems, and some player and NPC killing systems. It loops through every memory item on a character that has a specified flag.

For example, a character has 4 memory items with the following names and flags:
{|
| Ellessar || 02000
|-
| Sorea || 022bc
|-
| Introvert || 0740d
|-
| Enrath || 0c40d
|}

'''Script:'''<br />
<spherescript>[FUNCTION get_harmedby_mems]
REF1 = <UID> // As with FORCHARLAYER, the default object changes within the loop
FORCHARMEMORYTYPE memory_harmedby // Loop through memory items with flag 00010=memory_harmedby
REF1.SYSMESSAGE There is a memory item with name <NAME>, uid <UID>, flags <COLOR> and one of its flag is also 00010.
ENDFOR</spherescript>

'''Result:'''<br />
On your screen you would see:

''There is a memory item with name Ellessar, uid 04f000001, flags 02000 and one of its flag is also 02000.''<br />
''There is a memory item with name Sorea, uid 04f000002, flags 022bc and one of its flag is also 02000.''<br />
''There is a memory item with name Introvert, uid 04f000003, flags 0740d and one of its flag is also 02000.''<br /></tt>

'''Note that there are only three messages, because the memory item "Enrath" does not have the flag 02000.'''

===FORCHARS===
FORCHARS is a FOR loop that you can use to check all mobiles (player and NPC) within a set radius of an object.

The correct syntax being ''FORCHARS x'' where ''x'' is the radius in tiles the loop will cover.

* '''FORCHARS 2''' would check any mobile within a 2 tile radius
* '''FORCHARS 18''' would check the area inside your screen
* '''FORCHARS 6144''' would check the entire world map

One example of a function using FORCHARS

<spherescript>[FUNCTION kill_vendors]
FORCHARS 6144 // checks entire map
IF (<BRAIN> == brain_vendor) //argument for what will be acted upon within this function
KILL // action
ENDIF
ENDFOR</spherescript>

As with all FOR loops you have to stipulate inside the loop what it is to act upon, if you are restricting it to certian players/npcs (or in the case of FORITEMS, items) otherwise it will perform the action upon all players/npcs within the radius of the loop.

In this case the loop checks for any Vendor npc's and kills them.

===FORCLIENTS, FORPLAYERS===
FORCLIENTS and FORPLAYERS are FOR loops, both are used to affect a clients/players in certain radius. If you do not set the radius, radius 18 is used as default. While FORCLIENTS only acts on player characters who are logged in, FORPLAYERS acts on each and every player character, even if logged off.

'''Usage:'''<br />
<spherescript>[FUNCTION radius_players]
FORCLIENTS 25
IF (<ACCOUNT.PLEVEL> <= 1) // Affects only logged in players, not staff
SAY I am here!
ENDIF
ENDFOR</spherescript>

===FORCONT===
FORCONT is a type of FOR loop. It loops through every item in a container. The default object inside the loop will be the item currently being looped over.

'''Usage:'''<br />
<spherescript>[FUNCTION rem_spellbooks]
FORCONT <FINDLAYER.21.UID> 10 // <FINDLAYER.21.UID> - UID of a container, 10 - how many subcontainers the function goes through, if set 0, it affects only items in container with UID
IF (<BASEID> == i_spellbook)
REMOVE
ENDIF
ENDFOR</spherescript>

===FORCONTID===
FORCONTID is a FOR loop that works in a similar way to FORCONT, except that it will only cycle through items that have a specific BASEID. You can set the amount of subcontainers to loop through, like the FORCONT example.

'''Usage:'''<br />
<spherescript>[FUNCTION rem_spellbooks2]
FORCONTID i_spellbook 10
REMOVE
ENDFOR</spherescript>

===FORCONTTYPE===
This is another FOR loop that is almost identical to FORCONTYPE. The only difference is that instead of looping through items with a specific BASEID, it will loop through items with a specific TYPE. Following the spellbooks remover example:

'''Usage:'''<br />
<spherescript>[FUNCTION rem_spellbook3]
FORCONTTYPE t_spellbook
REMOVE
ENDFOR</spherescript>

===FORINSTANCES===
You may have seen scripts that do something like the following:

<spherescript>[FUNCTION removespawns]
FORITEMS 9999
IF (<BASEID> == i_worldgem_bit)
REMOVE
ENDIF
ENDFOR</spherescript>

At a glance this script looks like a fairly useful script that can be used to remove all of your i_worldgem_bit (spawn) items from the server. If you attempt to run it you will most certainly notice that your server pauses for a signicantly long time (on a well-populated server you may even end up waiting a whole minute for the script to run), even if you only have several instances of the item on the server! The reason that this happens is because ''FORITEMS 9999'' will loop through ''every'' item within the 9999 tile radius, so the code will be looping hundreds or thousands of times when you only wanted to affect a handful of items!

To resolve this issue we have FORINSTANCES. This is a special loop which will loop through all instances of a given character or item BASEID that exist on the server. This offers the following advantages over using ''FORITEMS/FORCHARS 9999'':
* Sphere will only run your script for objects with the BASEID you are interested in.
* Sphere knows how many instances of the object exist, so can abort the loop at an appropriate time.
* Items inside containers (e.g. character backpacks or player banks) will not be missed out.

So with this in mind, the above script can be rewritten to the following:

<spherescript>[FUNCTION removespawns]
FORINSTANCES i_worldgem_bit
REMOVe
ENDFOR</spherescript>

Now when you run this script you should notice a significant drop in the execution time.

'''Note:''' Since Sphere still has to internally search for references to the objects you're after you may find that on well-populate servers there is still a noticable pause. If you need to use this kind of loop then you should do so sparingly, and if you need to regularly use this then you may wish to consider finding a more optimal way of implementing your script(s).

===FORITEMS===
FORITEMS works in much the same way that FORCHARS does, except it checks for ITEMS within the set radius as opposed to characters. Default obejct is set to the item which can be affected.

A basic example of a function using FORITEMS:

<spherescript>[FUNCTION Spawn_remover]
FORITEMS 6144 //once again it checks the entire map
IF (<TYPE> == t_spawn_char) //if this arguement is met
REMOVE //remove it
ENDIF //end the IF arguement
ENDFOR //end the FOR loop </spherescript>

===FOROBJS===
FOROBJS works in the same way that FORITEMS and FORCHARS does with the exception that this loop will find both characters '''AND''' items within the specified radius.

==WHILE==
WHILE is a ''conditional loop'', a block of code that will repeat itself whilst a given condition is true. Basically you can think of this as being an IF..ENDIF block that will run indefinately until the IF statement returns false.

'''ALWAYS AND ALWAYS:'''
# End WHILE blocks with ENDWHILE.
# Perform some action within the WHILE block that will change the outcome of the conditional statement.

For example:

<spherescript>[FUNCTION remove_all_mems]
WHILE (<FINDID.i_memory.UID>) // continue to loop whilst an i_memory item is found inside the object
FINDID.i_memory.REMOVE // remove a memory item
ENDWHILE</spherescript>

Whilst inside the loop, LOCAL._WHILE can be used to access the number of times that the script has looped so far. In some situations you may want to use this to impose a 'limit' on how many times your WHILE block can loop before it is forced to exit. An example of this could be:

<spherescript>[FUNCTION random_health]
WHILE (<HITS> > 10) && (<LOCAL._WHILE> < 20) // loop whilst the character has more than 10 health, but no more than 20 times
HITS = <R1,100> // set the character's health to a random value between 1 and 100
ENDWHILE</spherescript>

Since random numbers are.. random.. it is in theory possible that the health will never be set to a value less than or equal to 10. By checking LOCAL._WHILE inside the WHILE condition we add protection against the script looping indefinately and freezing the server.

==TRY==

===TRY===
TRY can be used to execute a line of script where the left hand side (i.e. a property being set or a function being called) is based on the value of an expression.

For example, we may have the following script:

<spherescript>LOCAL.TEST = 05
SRC.TAG0.MYTAG_<LOCAL.SOME> = 1234</spherescript>

Sphere will add a TAG named "MYTAG_<LOCAL.SOME>" with a value of "1234", when really we were hoping for "MYTAG_05". We can use TRY to accomplish this:

<spherescript>LOCAL.TEST = 05
TRY SRC.TAG0.MYTAG_<LOCAL.SOME> = 1234</spherescript>

This causes Sphere to evaluate the entire line first, as "<tt>SRC.TAG0.MYTAG_05 = 1234</tt>" and then run it, giving us the "MYTAG_05" TAG as we were after.

'''Note:''' Since 27-11-2006 the TRY function has become obsolete. Sphere will now always evaluate the entire line before executing it.

===TRYP===
This is the same as the TRY function, except that a PLEVEL parameter is also supplied. If SRC's PLEVEL is less than this value then the line will not be executed, for example:

<spherescript>TRYP 4 UID.<TAG.CHARUID>.NAME Yerk</spherescript>

The above line will not be executed if SRC's PLEVEL is less than 4, so it will not run for players but it will to GM and above. This is almost the same as writing:

<spherescript>IF (<SRC.ACCOUNT.PLEVEL> >= 4)
UID.<TAG.CHARUID>.NAME Yerk
ENDIF</spherescript>

However, with TRYP the line will also run if there is no SRC (in an @Timer trigger, for example). So a more accurate scripted equivalent would be:

<spherescript>IF !(<SRC>)
TRY UID.<TAG.CHARUID>.NAME Yerk
ELSEIF (<SRC.ACCOUNT.PLEVEL> >= 4)
TRY UID.<TAG.CHARUID>.NAME Yerk
ENDIF</spherescript>

===TRYSRC===
As already mentioned in a previous chapter, the TRYSRC function can be used to override the SRC object for a given line.

The syntax for this function is <tt>TRYSRC uid command</tt>, where <tt>uid</tt> is the UID of the character who you want to become SRC, and <tt>command</tt> is the command you want to execute.

<spherescript>ON=@Timer
// place 5000 gold coins in LINK's backpack
SERV.NEWITEM i_gold
NEW.AMOUNT = 5000
TRYSRC <LINK.UID> NEW.BOUNCE // the BOUNCE function places an item into SRC's backpack
RETURN 1</spherescript>

===TRYSRV===
TRYSRV is similar to the TRYSRC command except that rather than running a command with a specific character as SRC, the command is instead executed with SRC set to the SERV object.

This can be desirable in the following situations:
* Certain properties of accounts, such as passwords, are protected against being accessed unless SRC has a PLEVEL of 7 (owner). It would be incredibly dangerous and unwise to set a player's PLEVEL to 7, even temporarily, but the SERV object is always considered to have a PLEVEL of 7.
* Certain functions/commands behave differently with a character as SRC, for example:
** SERV.NEWNPC will automatically set the new NPC's position to beside the SRC character. By using <tt>TRYSRV SERV.NEWNPC</tt> you can avoid players seeing an NPC 'flicker' on and off their screen.

==SERV==

===CHARDEF===
Let's say you wanted to retrieve the DAM property from, say, a Liche. Because DAM isn't a character property, we can only get the property from the CHARDEF. (Technically, there is a DAM property for characters, but it is not what we're looking for.)

<spherescript>[FUNCTION f_return_char_prop]
LOCAL.DAM = <SERV.CHARDEF.<ARGS>.DAM></spherescript>

With the above example, Sphere will take the argument passed (ARGS), then try to store the DAM property from the corresponding CHARDEF into LOCAL.DAM.

Pretty simple, right?

===ITEMDEF===
This works similar to SERV.CHARDEF, only it works on ITEMDEFs. Let's say you wanted to get the SKILL property from a character's equipped weapon.

Here's an example:

<spherescript>[FUNCTION f_return_wep_skill]
LOCAL.WEP_SKILL = <SERV.ITEMDEF.<ARGS>.SKILL></spherescript>

That would store the SKILL property of whatever ITEMDEF passed (ARGS) into LOCAL.WEP_SKILL. And this can get much more complex. As an example, I recently wrote a script that does the following:
* Use QVAL to find the equipped weapon.
* Store the weapon found in REF1.
* Check to see if REF1 returned a weapon UID.
* Store the DAM property for the weapon in LOCAL.WEP_DAM.

<spherescript>[FUNCTION f_weapon_dam]
REF1 = <QVAL <FINDLAYER.1.UID> ? <FINDLAYER.1.UID> : <FINDLAYER.2.UID>>
IF (<REF1>) // REF1 is true; weapon found.
LOCAL.WEP_DAM = <SERV.ITEMDEF.<REF1.BASEID>.DAM>
ENDIF
RETURN <LOCAL.WEP_DAM></spherescript>

That's not too complex, is it?

===LOG===
This functions is very good if you want to see when a player makes something or say something or when want to know the result of formulas in your scripts. This, is for writing messages onto the console (and logs). It is really simple to use:

<spherescript>SERV.LOG Hi world</spherescript>

And when you look at console it shows something like:

<spherescript color="darkgreen">21:56:(YourScript.scp,2)Hi world</spherescript>

Easy and useful.

'''Note:''' If for some reason you don't want the script name to appear in the log, prefix your log message with the '@' character (prefix the message with two '@' characters (@@) if you actually want to start the message with the @ symbol.

===MAP===
The SERV.MAP function allows you to read the properties of a specific point on a map. There are two syntaxes that can be used:
# <tt><SERV.MAP(x,y,map)>.KEY</tt>
# <tt><SERV.MAP(x,y,z,map)>.KEY</tt>

You may notice a slight 'peculiarity' in these syntaxes and you should be aware of them so that they don't catch you out: When there are 3 parameters given, the third parameter is used as the map number to access. When 4 parameters are given, the third parameter is the height (Z) and the fourth becomes the map number.

The KEY can be a number of things:

{|
|-
| ISNEARTYPE type distance checkmulti || Returns 1 if an item exists near the point within <distance> tiles. If <checkmulti> is 1 then multi components will also be checked.
|-
| REGION || Access the REGION at the map point.
|-
| ROOM || Access the ROOM at the map point.
|-
| SECTOR || Access the SECTOR at the map point.
|-
| STATICS || The number of static items at the map point.
|-
| STATICS.n.ID || The ID of the nth static item at the map point (n starts at 0)
|-
| STATICS.n.COLOR || The COLOR of the nth static item at the map point (n starts at 0)
|-
| STATICS.n.Z || The Z level of the nth static item at the map point (n starts at 0)
|-
| STATICS.n.* || If the STATICS.n.KEY does not match any of the above properties, the value will be taken from the static's ITEMDEF in the scripts
|-
| TERRAIN || The ID of the terrain at the map point.
|-
| TYPE || The type of terrain at the map point.
|-
| X, Y, Z, M, MAP || Access the X/Y/Z/MAP values at the map point.
|-
| COMPONENTS || The number of components items at the map point.
|-
| COMPONENTS.n.ID || The ID of the nth component item at the map point (n starts at 0)
|-
| COMPONENTS.n.Z || The Z level of the nth component item at the map point (n starts at 0)
|}

===NEWDUPE===
When you use the <font color="darkred">.DUPE</font> command you can create a 'clone' of a targeted item. The NEWDUPE function allows this functionality to be reproduced within scripts.

The syntax of the function is <tt>NEWDUPE uid</tt>, where uid is the UID of the object you want to clone. After running this function, the SERV.NEW reference will be set to the newly cloned item. You should know that it creates the 'duped' item exactly on the same spot where the targeted item exists. So you may have to move it anywhere else or it will maybe crush your stack.

Here is an example, the script below will clone the character's weapon and place it in their backpack:

<spherescript>[FUNCTION f_dupeweapon]
IF (<WEAPON.UID>)
SERV.NEWDUPE <WEAPON>
BOUNCE <NEW.UID>
ENDIF</spherescript>

===NEWITEM===
This is an easy function, used to create items. Many of you learned in 55i tutorials the format of NEWITEM, well, this changed on 56b and this is mainly to explain that change.

Now, you can't use this function on some player, you have to create it on SERV. Also, the reference to the new item isn't SRC.ACT anymore. It changed to NEW, so, if i want to create an item with the color 9, it will look like this:

<spherescript>SERV.NEWITEM i_example
NEW.COLOR 9</spherescript>

As you can see, it is really easy to use. There are also additional parameters that can be optionally passed into NEWITEM:

<tt>NEWITEM id, amount, cont, triggerEquip</tt>

So if I want to create 3 i_test in SRC's backpack I should do:

<spherescript>SERV.NEWITEM i_test, 3, <SRC.FINDLAYER.21.UID>,1</spherescript>

Easy, uh?

===NEWNPC===
This function can be used to create NPCs in the world. The syntax is <tt>NEWNPC id</tt>, where <tt>id</tt> is the BASEID of the character you wish to create. The newly created character can be accessed via the NEW reference.

The following function creates a headless and moves it to within 10 tiles of the default object.

<spherescript>[FUNCTION f_createnpc]
SERV.NEWNPC c_headless
NEW.MOVENEAR <UID> 10</spherescript>

'''Note''' It is also possible to create player characters this way, by setting the ACCOUNT property after creating the new character.

===NEWSUMMON===
This function similar to NEWNPC but is specific to summons. This will allow you to create a new summoned creature for a specific time.

<spherescript>
[FUNCTION f_createsummon]
SERV.NEWSUMMON=c_ogre,15
NEW.P=<p>
</spherescript>

This example will summon and Ogre for 15 seconds at your current location.

===SKILL===
Well, this is an easy function, like the others. This one refers to the SKILL section.

You can see the skill properties in sphere_skills.scp. I'll explain how it works:

<spherescript>LOCAL.SKILL = <SERV.SKILL.<ACTION>.KEY></spherescript>

With that line you get the Skill Key (Alchemy, ex.).

There are 3 ways to use SERV.SKILL: Key, Defname, Number.

Any of them are accepted, and if you see, in most of the cases people use Action to get the Key and get the player skill amount.

You can find many uses for it, all you need is some imagination.

[[Category:Tutorials]]

@SpellEffectTick

2022-09-23T00:48:27Z

Soulless:

==Description==
This trigger fires when a character successfully casts a spell.

Fires on:
* [[Characters]]

==References==
The following object references are explicitly available for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Name''' || '''Description'''
|-
| [[I]] || The object that is going to be affected.
|-
| [[SRC]] || The object that is going to be affected.

|}

==Arguments==
The following arguments are set for this trigger. If an argument is marked as "In" then a value will be passed in to the trigger, if an argument is marked as "Out" then it can be set to a value to affect Sphere's behaviour:

{| border="1" cellspacing="4" cellpadding="4"
| '''Argument''' || '''In/Out''' || '''Description'''
|-
| ARGN1 || I || Spell Id
|-
| ARGN2 || IO || Spell Level
|-
| ARGO || IO || The spell memory.(Argo.link holds the caster UID)
|-
| LOCAL.CHARGES || IO || How many charges are left on the spell memory, this will be automatically decreased by 1 at the end of the method execution. Default value is 1.
|-
| LOCAL.DELAY || IO || How many seconds until the next spell effect tick. Default value is 5 seconds.
|-
| LOCAL.EFFECT || IO || The effect value of the spell, harmful or beneficial (if SPELLFLAG_HEAL is enabled).
|-
| LOCAL.DAMAGETYPE || IO || The damage type of the spell, if you are making a custom spell you must set a value otherwise the spell will not cause damage.
|}

==Return Values==
The following return values are explicitly defined for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Return Value''' || '''Description'''
|-
| 1 || Destroy the spell memory and block the spell execution.
|-
| 0 || If the spell has the flag SPELLFLAG_SCRIPTED blocks the spell execution

|}

[[Category: Reference Compendium]]
[[Category: Triggers]]

@SpellEffectTick

2022-09-23T00:48:11Z

Soulless:

==Description==
This trigger fires when a character successfully casts a spell.

Fires on:
* [[Characters]]

==References==
The following object references are explicitly available for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Name''' || '''Description'''
| [[I]] || The object that is going to be affected.
|-
| [[SRC]] || The object that is going to be affected.

|}

==Arguments==
The following arguments are set for this trigger. If an argument is marked as "In" then a value will be passed in to the trigger, if an argument is marked as "Out" then it can be set to a value to affect Sphere's behaviour:

{| border="1" cellspacing="4" cellpadding="4"
| '''Argument''' || '''In/Out''' || '''Description'''
|-
| ARGN1 || I || Spell Id
|-
| ARGN2 || IO || Spell Level
|-
| ARGO || IO || The spell memory.(Argo.link holds the caster UID)
|-
| LOCAL.CHARGES || IO || How many charges are left on the spell memory, this will be automatically decreased by 1 at the end of the method execution. Default value is 1.
|-
| LOCAL.DELAY || IO || How many seconds until the next spell effect tick. Default value is 5 seconds.
|-
| LOCAL.EFFECT || IO || The effect value of the spell, harmful or beneficial (if SPELLFLAG_HEAL is enabled).
|-
| LOCAL.DAMAGETYPE || IO || The damage type of the spell, if you are making a custom spell you must set a value otherwise the spell will not cause damage.
|}

==Return Values==
The following return values are explicitly defined for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Return Value''' || '''Description'''
|-
| 1 || Destroy the spell memory and block the spell execution.
|-
| 0 || If the spell has the flag SPELLFLAG_SCRIPTED blocks the spell execution

|}

[[Category: Reference Compendium]]
[[Category: Triggers]]

@SpellEffectTick

2022-09-23T00:48:00Z

Soulless:

==Description==
This trigger fires when a character successfully casts a spell.

Fires on:
* [[Characters]]

==References==
The following object references are explicitly available for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Name''' || '''Description'''
| [[I]] || The object that is going to be affected.
|-
| [[SRC]] || The object that is going to be affected.

|}

==Arguments==
The following arguments are set for this trigger. If an argument is marked as "In" then a value will be passed in to the trigger, if an argument is marked as "Out" then it can be set to a value to affect Sphere's behaviour:

{| border="1" cellspacing="4" cellpadding="4"
| '''Argument''' || '''In/Out''' || '''Description'''
|-
| ARGN1 || I || Spell Id
|-
| ARGN2 || IO || Spell Level
|-
| ARGO || IO || The spell memory.(Argo.link holds the caster UID)
|-
| LOCAL.CHARGES || IO || How many charges are left on the spell memory, this will be automatically decreased by 1 at the end of the method execution. Default value is 1.
|-
| LOCAL.DELAY || IO || How many seconds until the next spell effect tick. Default value is 5 seconds.
|-
| LOCAL.EFFECT || IO || The effect value of the spell, harmful or beneficial (if SPELLFLAG_HEAL is enabled).
|-
| LOCAL.DAMAGETYPE || IO || The damage type of the spell, if you are making a custom spell you must set a value otherwise the spell will not cause damage.
|}

==Return Values==
The following return values are explicitly defined for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Return Value''' || '''Description'''
|-
| 1 || Destroy the spell memory and block the spell execution.
| '''Return Value''' || '''Description'''
|-
| 0 || If the spell has the flag SPELLFLAG_SCRIPTED blocks the spell execution

|}

[[Category: Reference Compendium]]
[[Category: Triggers]]

@SpellEffectTick

2022-09-23T00:47:43Z

Soulless:

==Description==
This trigger fires when a character successfully casts a spell.

Fires on:
* [[Characters]]

==References==
The following object references are explicitly available for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Name''' || '''Description'''
| [[I]] || The object that is going to be affected.
|-
| [[SRC]] || The object that is going to be affected.

|}

==Arguments==
The following arguments are set for this trigger. If an argument is marked as "In" then a value will be passed in to the trigger, if an argument is marked as "Out" then it can be set to a value to affect Sphere's behaviour:

{| border="1" cellspacing="4" cellpadding="4"
| '''Argument''' || '''In/Out''' || '''Description'''
|-
| ARGN1 || I || Spell Id
|-
| ARGN2 || IO || Spell Level
|-
| ARGO || IO || The spell memory.(Argo.link holds the caster UID)
|-
| LOCAL.CHARGES || IO || How many charges are left on the spell memory, this will be automatically decreased by 1 at the end of the method execution. Default value is 1.
|-
| LOCAL.DELAY || IO || How many seconds until the next spell effect tick. Default value is 5 seconds.
|-
| LOCAL.EFFECT || IO || The effect value of the spell, harmful or beneficial (if SPELLFLAG_HEAL is enabled).
|-
| LOCAL.DAMAGETYPE || IO || The damage type of the spell, if you are making a custom spell you must set a value otherwise the spell will not cause damage.

==Return Values==
The following return values are explicitly defined for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Return Value''' || '''Description'''
|-
| 1 || Destroy the spell memory and block the spell execution.
| '''Return Value''' || '''Description'''
|-
| 0 || If the spell has the flag SPELLFLAG_SCRIPTED blocks the spell execution

|}

[[Category: Reference Compendium]]
[[Category: Triggers]]

@SpellEffectTick

2022-09-23T00:40:15Z

Soulless:

==Description==
Fired when a spell memory has one or more charges (more2) and the spellflag_tick

Fires on:
* [[Characters]]

==References==
The following object references are explicitly available for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Name''' || '''Description'''
|-
| [[ARGN1]] || Spell ID
|-
| [[ARGN2]] || Spell Level
|-
| [[ARGO]] || The spell memory.(Argo.link holds the caster UID)
|}

==Arguments==
The following arguments are set for this trigger. If an argument is marked as "In" then a value will be passed in to the trigger, if an argument is marked as "Out" then it can be set to a value to affect Sphere's behaviour:

{| border="1" cellspacing="4" cellpadding="4"
| '''Argument''' || '''In/Out''' || '''Description'''
|-
| ARGN1 || I || The spell that was cast.
|-
| ARGN2 || IO || The strength of the spell.
|-
| LOCAL.CREATEOBJECT1 || O || For field spells, overrides the item [[BASEID]] to use for the east-west direction.

For summon spells, overrides the character [[BASEID]] to summon.
|-
| LOCAL.CREATEOBJECT2 || O || For field spells, overrides the item [[BASEID]] to use for the north-south direction.
|-
| LOCAL.FIELDGAUGE || O || For field spells, overrides the default gauge of the field (1).
|-
| LOCAL.FIELDWIDTH || O || For field spells, overrides the default width of the field (7).
|-
| LOCAL.EFFECTCOLOR ||O || For field spells, overrides the color of the fields.
|}

==Return Values==
The following return values are explicitly defined for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Return Value''' || '''Description'''
|-
| 1 || Aborts casting the spell.
|}

[[Category: Reference Compendium]]
[[Category: Triggers]]

@SpellEffectTick

2022-09-23T00:39:31Z

Soulless: Created page with "==Description== Fired when a spell memory has one or more charges (more2) and the spellflag_tick Fires on: * Characters ==References== The following object references..."

==Description==
Fired when a spell memory has one or more charges (more2) and the spellflag_tick

Fires on:
* [[Characters]]

==References==
The following object references are explicitly available for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Name''' || '''Description'''
|-
| [[ARGO]] || The source of the spell. Could be the [[Items|item]] used to cast the spell (e.g. a wand or scroll) or the [[Characters|character]] casting the spell.
|-
| [[I]] || The [[Characters|character]] casting the spell.
|-
| [[SRC]] || The [[Characters|character]] casting the spell.
|-
| [[ACT]] || The target of the spell, if any.
|}

==Arguments==
The following arguments are set for this trigger. If an argument is marked as "In" then a value will be passed in to the trigger, if an argument is marked as "Out" then it can be set to a value to affect Sphere's behaviour:

{| border="1" cellspacing="4" cellpadding="4"
| '''Argument''' || '''In/Out''' || '''Description'''
|-
| ARGN1 || I || The spell that was cast.
|-
| ARGN2 || IO || The strength of the spell.
|-
| LOCAL.CREATEOBJECT1 || O || For field spells, overrides the item [[BASEID]] to use for the east-west direction.

For summon spells, overrides the character [[BASEID]] to summon.
|-
| LOCAL.CREATEOBJECT2 || O || For field spells, overrides the item [[BASEID]] to use for the north-south direction.
|-
| LOCAL.FIELDGAUGE || O || For field spells, overrides the default gauge of the field (1).
|-
| LOCAL.FIELDWIDTH || O || For field spells, overrides the default width of the field (7).
|-
| LOCAL.EFFECTCOLOR ||O || For field spells, overrides the color of the fields.
|}

==Return Values==
The following return values are explicitly defined for this trigger:

{| border="1" cellspacing="4" cellpadding="4"
| '''Return Value''' || '''Description'''
|-
| 1 || Aborts casting the spell.
|}

[[Category: Reference Compendium]]
[[Category: Triggers]]

FEVAL

2022-09-15T15:53:51Z

Soulless: /* Description */

=Description=
FEval is a function that returns the given value treating the last number as a decimal and removing it, the best example is to retrieve your skill points without decimals.

=Usage=
<spherescript "darkblue">
[function ShowAlchemy]
alchemy=99.9
say Alchemy is: <feval <alchemy>> // This will say 'Alchemy is: 99', removing the last number (.9).</spherescript>

Script Debugging

2022-08-28T08:25:29Z

Soulless:

So you've got a problem with a script and you don't know where to turn? Or everyone you've spoken to doesn't have the answers you seek? You're about to start pulling out your hair, you feel alone and lost, and no one can seem to help you. Well worry no more, you're about to help yourself! Let's talk about debugging your script

We'll go through some examples here to explain how one could get helpful information that will lead them to their solutions. Each situation will have it's own unique methods to help you use the tools at your disposal to fix the problem, or guide you to finding out more helpful information.

==Problems Understanding A Trigger==
Uncertain how a trigger works?

This is a great example from MalucoBeleza that illustrates the concept of logging out your results to the console for further insight into what objects a trigger is referencing. This can help you make sure that you are referencing the right object in game and that whatever follows will behave as expected.

Let's say you want to use a trigger that will fire when you kill someone, and when you kill that person you want to give the killer some experience points. You need to reference both the person being killed and the person that killed them.

The trigger in this example is [[@Kill]]. One may think that they will use the default object I as the killer and that SRC will be the person being killed. or that ACT would be the person being killed. But it is best not to assume any of these triggers will use any object reference the same as another, or even the same as a similar trigger. The best practice is to take yourself to the Spherewiki (as YOU already have) and pull up the trigger you are looking for under the Reference Compendium > [[Objects]] > [[Characters]], this will give you a very good idea of what references you can make in that trigger. Once you have that information you can begin to see what you are able to work with and how you can work with it.

As MalucoBeleza points out, this practice is required to get proper knowledge to work with a trigger

When dealing with a trigger that is new to you... its essential to check the wiki and do tests like this:

ON=@Kill
SERV.LOG NAME: <NAME>
SERV.LOG I.NAME: <I.NAME>
SERV.LOG SRC.NAME: <SRC.NAME>
SERV.LOG ARGO.NAME: <ARGO.NAME>
SERV.LOG <NAME> (<UID>) HAVE JUST KILLED <ARGO.NAME> (<ARGO>)

Debugging is also a great tool when you are performing calculations. Let’s say that you want to create your own combat system, such as:

ON=@Hit
SERV.LOG <NAME> HAVE JUST HIT <SRC.NAME>
IF (<WEAPON>)
SERV.LOG A WEAPON WAS USED: <WEAPON.NAME>
SERV.LOG <WEAPON.NAME>'S DAMAGE IS <WEAPON.DAM.LO> - <WEAPON.DAM.HI>
ELSE
SERV.LOG NO WEAPON WAS USED.
SERV.LOG <NAME>'S DAMAGE IS <DAM>
ENDIF

SERV.LOG DAMAGE STARTED AS <ARGN1>

SERV.LOG THE SKILL USED IN THIS ATTACK IS <ACTION>
IF (<ACTION> == WRESTLING) || (<ACTION> == MACEFIGHTING)
ARGN1 = <EVAL <ARGN1> + (<STR>/8)> //APPLY YOUR FORMULA HERE

ELIF (<ACTION> == ARCHERY) || (<ACTION> == FENCING)
ARGN1 = <EVAL <ARGN1> + (<DEX>/8)>

ELIF (<ACTION> == SWORDSMANSHIP)
ARGN1 = <EVAL <ARGN1> + (<DEX>/16) + (<STR>/16)>

ENDIF

SERV.LOG DAMAGE AFTER STATS BONUS ACCORDING TO THE SKILL IS <ARGN1>

IF (<SRC.ISPLAYER>) //PLAYER HITS ANOTHER PLAYER
SERV.LOG THE ARMOR OF THE DEFENDANT IS <SRC.ARMOR>
LOCAL.DAMAGE_REDUCTION = <EVAL <SRC.ARMOR>/20> //APPLY YOUR FORMULA HERE

ELSE //PLAYER HITS A NPC
SERV.LOG THE ARMOR OF THE DEFENDANT IS <SRC.AC>
LOCAL.DAMAGE_REDUCTION = <EVAL <SRC.AC>/20> //APPLY YOUR FORMULA HERE

ENDIF
ARGN1 -= <LOCAL.DAMAGE_REDUCTION>
SERV.LOG AFTER DAMAGE REDUCTION OF <LOCAL.DAMAGE_REDUCTION>, DAMAGE IS <ARGN1>

==Console Errors Regarding Scripts==
You are getting errors on your console, and it's telling you about a script but you aren't quite sure what to do. Let's see one as an example :

00:17:ERROR:(i_dye_tubs.scp,52)Range isn't closed by a '}' character.

Okay from this error we can see the filename 'i_dye_tubs' and the line number is 52. The error is that the 'Range isn't closed by a '}' character.' so let's go see what this line looks like and what we the appropriate line fix is:

So here's what line 52 from i_dye_tubs.scp looks like :
color={047e 049a

We can see above that its missing a } at the end just like the console error notified us about. The fix is to simply add the missing }.

this is a very elementary example but this explains the process of breaking down a console error. It's always the same for these script errors : "filename, line number, error description". With large complicated systems paying attention to the exact nature of your console error will guide you towards figuring out how to fix it.

Script Debugging

2022-08-28T08:25:23Z

Soulless: /* Situations */

Script Debugging

2022-08-28T08:25:09Z

Soulless: /* Situations */

So you've got a problem with a script and you don't know where to turn? Or everyone you've spoken to doesn't have the answers you seek? You're about to start pulling out your hair, you feel alone and lost, and no one can seem to help you. Well worry no more, you're about to help yourself! Let's talk about debugging your script

==Situations==
We'll go through some examples here to explain how one could get helpful information that will lead them to their solutions. Each situation will have it's own unique methods to help you use the tools at your disposal to fix the problem, or guide you to finding out more helpful information.

==Problems Understanding A Trigger==
Uncertain how a trigger works?

This is a great example from MalucoBeleza that illustrates the concept of logging out your results to the console for further insight into what objects a trigger is referencing. This can help you make sure that you are referencing the right object in game and that whatever follows will behave as expected.

Let's say you want to use a trigger that will fire when you kill someone, and when you kill that person you want to give the killer some experience points. You need to reference both the person being killed and the person that killed them.

The trigger in this example is [[@Kill]]. One may think that they will use the default object I as the killer and that SRC will be the person being killed. or that ACT would be the person being killed. But it is best not to assume any of these triggers will use any object reference the same as another, or even the same as a similar trigger. The best practice is to take yourself to the Spherewiki (as YOU already have) and pull up the trigger you are looking for under the Reference Compendium > [[Objects]] > [[Characters]], this will give you a very good idea of what references you can make in that trigger. Once you have that information you can begin to see what you are able to work with and how you can work with it.

As MalucoBeleza points out, this practice is required to get proper knowledge to work with a trigger

When dealing with a trigger that is new to you... its essential to check the wiki and do tests like this:

ON=@Kill
SERV.LOG NAME: <NAME>
SERV.LOG I.NAME: <I.NAME>
SERV.LOG SRC.NAME: <SRC.NAME>
SERV.LOG ARGO.NAME: <ARGO.NAME>
SERV.LOG <NAME> (<UID>) HAVE JUST KILLED <ARGO.NAME> (<ARGO>)

Debugging is also a great tool when you are performing calculations. Let’s say that you want to create your own combat system, such as:

ON=@Hit
SERV.LOG <NAME> HAVE JUST HIT <SRC.NAME>
IF (<WEAPON>)
SERV.LOG A WEAPON WAS USED: <WEAPON.NAME>
SERV.LOG <WEAPON.NAME>'S DAMAGE IS <WEAPON.DAM.LO> - <WEAPON.DAM.HI>
ELSE
SERV.LOG NO WEAPON WAS USED.
SERV.LOG <NAME>'S DAMAGE IS <DAM>
ENDIF

SERV.LOG DAMAGE STARTED AS <ARGN1>

SERV.LOG THE SKILL USED IN THIS ATTACK IS <ACTION>
IF (<ACTION> == WRESTLING) || (<ACTION> == MACEFIGHTING)
ARGN1 = <EVAL <ARGN1> + (<STR>/8)> //APPLY YOUR FORMULA HERE

ELIF (<ACTION> == ARCHERY) || (<ACTION> == FENCING)
ARGN1 = <EVAL <ARGN1> + (<DEX>/8)>

ELIF (<ACTION> == SWORDSMANSHIP)
ARGN1 = <EVAL <ARGN1> + (<DEX>/16) + (<STR>/16)>

ENDIF

SERV.LOG DAMAGE AFTER STATS BONUS ACCORDING TO THE SKILL IS <ARGN1>

IF (<SRC.ISPLAYER>) //PLAYER HITS ANOTHER PLAYER
SERV.LOG THE ARMOR OF THE DEFENDANT IS <SRC.ARMOR>
LOCAL.DAMAGE_REDUCTION = <EVAL <SRC.ARMOR>/20> //APPLY YOUR FORMULA HERE

ELSE //PLAYER HITS A NPC
SERV.LOG THE ARMOR OF THE DEFENDANT IS <SRC.AC>
LOCAL.DAMAGE_REDUCTION = <EVAL <SRC.AC>/20> //APPLY YOUR FORMULA HERE

ENDIF
ARGN1 -= <LOCAL.DAMAGE_REDUCTION>
SERV.LOG AFTER DAMAGE REDUCTION OF <LOCAL.DAMAGE_REDUCTION>, DAMAGE IS <ARGN1>

==Console Errors Regarding Scripts==
You are getting errors on your console, and it's telling you about a script but you aren't quite sure what to do. Let's see one as an example :

00:17:ERROR:(i_dye_tubs.scp,52)Range isn't closed by a '}' character.

Okay from this error we can see the filename 'i_dye_tubs' and the line number is 52. The error is that the 'Range isn't closed by a '}' character.' so let's go see what this line looks like and what we the appropriate line fix is:

So here's what line 52 from i_dye_tubs.scp looks like :
color={047e 049a

We can see above that its missing a } at the end just like the console error notified us about. The fix is to simply add the missing }.

this is a very elementary example but this explains the process of breaking down a console error. It's always the same for these script errors : "filename, line number, error description". With large complicated systems paying attention to the exact nature of your console error will guide you towards figuring out how to fix it.

Chapter 1

2022-08-19T19:40:40Z

Soulless:

{{Languages|Chapter_1}}

==Numbers==

The first thing you'll notice while looking through SPHERE scripts is the wide variety of ways to write numbers. Since numbers are insanely important to a SPHERE scripter, this is the first lesson in the series. By the end of the lesson, I hope that you have a general understanding of hexadecimal, decimal and binary numbering systems, and SPHERE's ways of identifying each. You will also know how to generate random numbers either from a series or from a list of choices.

The first thing you need to understand is that the way we count is not the only way to count. Our numbering system contains ten digits (0, 1, 2, 3, 4, 5, 6, 7, 8, and 9). Therefore, at the tenth number, we have to add an extra column to the number, and reset the first column to zero (1, 2, 3, 4, 5, 6, 7, 8, 9, 10). That's why our numbering system works the way it does.

In the decimal system, without realizing it, we write our numbers to mean powers of ten. For example, if you take the number 17282 (which I just made up), and divide it down we get this:

{| border="1"
| Power of ten || 4 || 3 || 2 || 1 || 0
|-
| Ten to that power || 10000 || 1000 || 100 || 10 || 1
|-
| Digit || 1 || 7 || 2 || 8 || 2
|}

To reach the number 17282 from here, we simply take ten to the power of the number in the top row, multiply it by the number in the bottom row, and then add all those numbers together. We get 10000 + 7000 + 200 + 80 + 2. Obviously, this is simplistic, and we do it without even realizing we're doing it. You're probably thinking "Riiight, what does Taran think he's getting at?" Well, we aren't so special that our counting system is the only way to count.

Now, there is another numbering system that is used almost solely by computers. It only contains two numbers (1 and 0) and is therefore called the binary (meaning two) system. Binary numbers look like this: 101011101101, and you often see them in ads for computers and other electronic equipment (oftentimes they are shown streaming out of a CD player on television commercials). Digits in the binary system are called bits (short for BInary digiT)Binary numbers are almost impossible to translate to decimal directly, and so some math must be done.

Binary works in the same way, by adding powers of a number. In the case of binary, since there are two numbers in the whole system, that number is naturally two. Here are some examples of powers of two. These numbers might look familiar to some people.

{| border="1"
| Power of 2 || Binary number || Decimal number
|-
| 0 || 1 || 1
|-
| 1 || 10 || 2
|-
| 2 || 100 || 4
|-
| 3 || 1000 || 8
|-
| 4 || 10000 || 16
|-
| 5 || 100000 || 32
|-
| 6 || 1000000 || 64
|-
| 7 || 10000000 || 128
|-
| 8 || 100000000 || 256
|-
| 9 || 1000000000 || 512
|-
| 10 || 10000000000 || 1024
|}

Ridiculous eh? :)

We need a better system! The reason we get such strange results is because 10 is not a power of two. We need to find a system where the number base IS a power of two. The most commonly used system used is base-16, or hexadecimal. I'm sure if you've perused the SPHERE boards, you've seen the word hex floating around. No, this isn't a curse or evil spell, it's a short way of saying "hexadecimal".

{| border="1"
| Binary || Decimal || Hexadecimal
|-
| 1 || 1 || 1
|-
| 10 || 2 || 2
|-
| 11 || 3 || 3
|-
| 100 || 4 || 4
|-
| 101 || 5 || 5
|-
| 110 || 6 || 6
|-
| 111 || 7 || 7
|-
| 1000 || 8 || 8
|-
| 1001 || 9 || 9
|-
| 1010 || 10 || A
|-
| 1011 || 11 || B
|-
| 1100 || 12 || C
|-
| 1101 || 13 || D
|-
| 1110 || 14 || E
|-
| 1111 || 15 || F
|-
| 10000 || 16 || 10
|}

See how it works? There are an extra six numbers added onto the end of the system, represented by the first six letters of the alphabet.

Now, in SPHERE scripting, you are almost NEVER going to be dealing with binary numbers that are NOT powers of two, and if you do, you can simply use any scientific calculator to figure it out. But it's a lot easier in hexadecimal.

(This is the last table, I promise!!)
{| border="1"
| Binary || Hexadecimal
|-
| 000000001 (1) || 01
|-
| 000000010 (2) || 02
|-
| 000000100 (3) || 04
|-
| 000001000 (4) || 08
|-
| 000010000 (5) || 010
|-
| 000100000 (6) || 020
|-
| 001000000 (7) || 040
|-
| 010000000 (8) || 080
|-
| 100000000 (9) || 0100
|}

As you can see, there's a bit of a pattern in the hexadecimal column. You might be thinking, there seems to be some sort of pattern of the numbers 1, 2, 4 and 8. And you would be right. Another detail you may notice is the zeros in front of the hexadecimal numbers (like 0100, rather than just 100). In SPHERE, that 0 tells the script "Hey, this number is HEX!" 0100 and 100 are very different numbers.

Let's say, for a SPHERE script, you need to set the 13th bit of a number (FLAGS, for example), you could write something like this:

'''SRC.FLAGS |= 8192'''

But would you really remember that 8192 is 2 to the 13th power? I didn't think so. What would be easier is to go down through your list in your head, until you reach the 13th number. (Remember, START AT ZERO when you're counting!)

{| border="1"
| 01 || 02 || 04 || 08 || 010 || 020 || 040 || 080 || 0100 || 0200 || 0400 || 0800 || 01000 || 02000
|-
| 2^0 || 2^1 || 2^2 || 2^3 || 2^4 || 2^5 || 2^6 || 2^7 || 2^8 || 2^9 || 2^10 || 2^11 || 2^12 || 2^13
|}

And there you have it. The first 14 powers of two in hexademical.

'''SRC.FLAGS |= 02000'''

The above code is identical to the previous example. 8192 (decimal) is EQUAL to 02000 (hexadecimal)

'''8192 = 02000'''

You may be saying, "How do I know he's just not making all of this up?" Well, our wonderful friends at Microsoft have provided us with a nice tool that converters from decimal to hexadecimal to binary to octal (ANOTHER numbering system that is useless in SPHERE, so we will not deal with it). It's called the Calculator. You may find it by clicking your start button, going to Programs, then Accessories. Calculator should be sitting there looking pretty. Once in the calculator program, go to the View menu, and click Scientific. You'll see the display drastically change. To convert a number between numbering systems, simply click on the original system (Dec), type a number (8192), then click on the button for the other system (Hex). Automagically, Windows will convert your decimal number to hexadecimal. Stick a zero on the front, and SPHERE will be perfectly happy with it.

This is probably the hardest thing in all of SPHERE scripting to understand. Luckily, because of the next section, you won't have to deal with scary numbers most of the time. If I still have you at the end of this lesson, I know you're going to do great!

Onward to some SPHERE scripting!

==Defnames==

Here's a list of scary numbers you might encounter while programming in SPHERE.

{| border="1"
| The Scary Number || What it means
|-
| 0eed || ID of a gold coin
|-
| 0dda || ID of a red moongate
|-
| 1650,1440 || Coordinates of Britain
|-
| 021 || The code number for red
|-
| 04000 || The invisible color
|-
| 04000efad || An item's serial number
|-
| 4 || The PLEVEL of a GM
|-
| 2048 (or 0800) || Flag for incognito spell
|-
| 010 (or 16) || Memory type for aggressors
|}

Obviously, no one is going to want to remember those numbers. Back in the old days, before SPHERE and TUS (pre-.50 SPHERE) and even into the mists of Grayworld (pre-.41 TUS), we all had to remember those numbers. I know all of those numbers I just said (except the serial number which I just made up), plus a couple dozen more, by heart. Luckily for those of you who don't like to sit around remembering numbers all day, SPHERE has developed a system whereby things can be identified by names instead of numbers.

Actually, the things are still identified by numbers. It's the numbers which are identified by the name.

In the game, type .add 0eed and press enter. A target will come up and you'll create a single gold piece.

Now type .add i_gold and press enter. You will create the same single gold piece.

Now which is easier to remember, 0eed or i_gold. I would say that i_gold wins by a long shot. But how does this magic happen? Let's take a look at the script definition for a piece of gold. Don't worry about understanding it. I'll explain item scripts in full in the next section! You can find this script in the file sphere_item_resources.scp.

<tt><font color="darkgreen">[ITEMDEF 0eed]<br />
//gold coin<br />
<font color="ff0000">DEFNAME=i_gold</font><br />
TYPE=T_GOLD<br />
VALUE=1<br />
CATEGORY=Provisions - Miscellaneous<br />
SUBSECTION=Coins<br />
DESCRIPTION=Gold Coin<br />
DUPELIST=0eee,0eef</font><br /></tt>

I have highlighted in red the line that really matters for the purposes of this lesson. Take note of the 0eed in the top line of the script, and then ignore the rest of it. That 0eed is the real item number of this item. We'll cover item numbers more in the next section.

But the real line we want to see the <font color="ff0000">DEFNAME=i_gold</font> line. This is where the script tells the server, "I want item 0eed to be identified by the text i_gold from here on." If you tried to refer to i_gold before the server read this script (more on reordering scripts in [[Chapter 2]], the server would spit out an error, but now it knows what that refers to, so you can use it in the game or in another script.

You should ALWAYS give items you create a DEFNAME that fits the item. Usually the defname will be defined in the [ITEMDEF] identifier itself (again, more on this later), but if you insist upon using numbers, be sure you give it an easy-to-remember name (not golden_gulash for a viking sword). It makes it easier to remember names than numbers.

A second way to define a DEFNAME is by using the [DEFNAME] tag in a script. Here is an example of that:

<tt><font color="darkgreen">[DEFNAME colors]<br />
color_blue 02<br />
color_red 021<br />
color_green 041</font><br /></tt>

You'll find a script similar to this in spheredefs.scp, another file that should be loaded before any other file.

Here's the rundown on this script, line by line:

'''Line 1''': This is where the type of script and the defname (yes colors is the defname of this script) is defined. This tells the server what type of script to expect between this and the next identifier (identifiers are the lines contained in square brackets). All identifiers have this format. The first parameter is the script type. These are numerous, and I will go over them as we get to them. The second parameter is either an ID number or a defname. In most cases, in the scripts you write, it will be a defname. The only exceptions to this I can think of would be if you used a program to insert a new item into the client files.

'''Lines 2-4''': These set up your individual DEFNAME pieces. It says that color_blue is equal to 02, color_red is equal to 021, and color_green is equal to 041. You may have any number of spaces between the name and the value. The definitions contained in spheredefs.scp are among the most useful you will encounter, as they prevent you from writing the long scary numbers we went over in the previous section. These include things like names for flags, names for item attributes, names for the built-in MIDI or MP3 music, names for memory types, and many other things. Look through the file to see what it offers you.

That's about it for DEFNAMEs. You'll see more of these later as we cover other types of scripts.

Now go on to learn about items.

==ITEMDEF==
Or, how to make a mountain from a molehill, SPHERE style

Most people make item scripting much harder than it needs to be. For the purposes of this tutorial, since there is a more advanced one later, we will simply go over the basics of an ITEM script, line by line. We'll be using the gold script from the previous lesson, provided I can find it again....

Ah, here it is, conveniently color coded for your viewing pleasure!

<spherescript>[ITEMDEF 0eed]
//gold coin
DEFNAME=i_gold
TYPE=T_GOLD
VALUE=1
CATEGORY=Provisions - Miscellaneous
SUBSECTION=Coins
DESCRIPTION=Gold Coin
DUPELIST=0eee,0eef</spherescript>

This is the simplest of item scripts, since it has no additional behaviors beyond existing. I will go through this line by line, describing to you what each line does, and how it affects the end result.

'''Line 1''': [ITEMDEF 0eed]

The first lines of an item script are frequently the most important. Basically, this line tells the server "Hey this is an item and I want it to be called 0eed!" The server then looks through one of the client files (specifically art.idx), and identifies whether or not this item is one of the built-in items. I think all items below 04500 are defined as built-in items, so never define a new item in that range. By typing this line, you tell the server that an item script is following. You also define 0eed as a valid item, which will definitely help later on when you try to give gold to players!

'''Line 2''': // gold coin

This is the SPHERE version of comment. C programmers will recognize the format immediately. If you type // on any line of code, everything beyond that is ignored by the script reader. This can be on a line by itself, or at the end of a line to explain what the specific line does. In all cases, it won't affect your program, just make it easier to read.

'''Line 3''': DEFNAME=i_gold

You should know by now what this does! If you don't, go back and read the previous lesson! It tells the server that i_gold and 0eed mean the same thing. In item scripts, all parameters are defined in that format:

variable=value

You will see later on, when we get into scripting, how that format will help you more than you would believe. Items have a good number of variables that you can define, including:

* DEFNAME
* ID
* TYPE
* VALUE
* RESOURCES
Other variables depend on the value of the TYPE. Which leads us right into...

'''Line 4''': TYPE=t_gold

The first thing you might say is "What the heck is t_gold?" Well it's a DEFNAME. Actually it's a number. And that number is 72. If you want to check me on this, look in spheredefs.scp, it's there! Writing TYPE=72 would have the exact same effect.

There are, currently, 183 built-in item types. These are hardcoded item types that contain predefined actions for an item. If an item has no type, when you click it, you get the "You cannot think of a way to use that item" message. There is a complete list of types, and how to set them up, here . All you need to know for now is that setting the type of this item to t_gold has no effect other than to make the item act like a gold coin (i.e. you can buy stuff with it!) Setting another item to type t_gold would probably make the server think that you can buy stuff with that item too. I've never tried this. It might be an interesting way to have unique currencies...

'''Line 5''': VALUE=1

This defines how much the item costs when purchased, in gold. Of course, this is one gold piece, which is worth, well, one gold piece. So the value of the item is one.

'''Lines 6-8''': CATEGORY, SUBSECTION, DESCRIPTION

These are lines used only by SPHERE's GM tool, Axis, which actually saves you a lot of work by typing ".add i_gold" for you. More importantly, it types ".add 01737" and things like that for you, for items that were not important enough to get their own separate DEFNAME.

'''Line 9''': DUPEITEM

It would be a ton of work for the SPHERE team to define all 8000 items that came with the game, especially when many of them are the same. (For an example of this, use the .xflip command on a door or sign. It cycles through all of the DUPEITEMs for that the item being flipped.) The numbers listed here are item numbers, which probably have not been defined yet. Here is the script for item 0eee:

<spherescript>[ITEMDEF 0eee]
//gold coins
DUPEITEM=0eed
CATEGORY=Provisions - Miscellaneous
SUBSECTION=Coins
DESCRIPTION=Gold Coins</spherescript>

As you can see, there is only one parameter for this whole item. It reiterates the DUPEITEM and sends the server looking to our 0eed (or i_gold) item for more information, such as TYPE and VALUE. DUPEITEM only exists to save typing. You probably won't use it.

==CHARDEF==
Or, what it takes to make a naked man who can stand around and say "Huh?"

NPCs... They make the world go around. They are what makes UO a unique multiplayer game. The monsters and NPCs you create make your server unique from any other. This section of chapter one will cover how to create a simple naked man who walks around and says little more than "Huh?" (or "Stop thief!" if you tell him to!).

First of all, we'll look at the script for a simple naked man. I'm pulling this out of spherechar_human.scp.

<spherescript>[CHARDEF 0190]
DEFNAME=c_man
Name=Man
ICON=i_pet_MAN
CAN=MT_EQUIP|MT_WALK|MT_RUN|MT_USEHANDS
RESOURCES=i_flesh_head, i_flesh_torso, i_flesh_right_arm, i_flesh_left_arm
FOODTYPE=15 t_food, t_fruit
DESIRES=i_gold,e_notoriety
AVERSIONS=t_TRAP,t_eerie_stuff
SHELTER=r_house
BLOODCOLOR=0

TSPEECH=spk_human_prime
TSPEECH=spk_human_default
TEVENTS=e_Human_HearUnk
DESCRIPTION=Man
SUBSECTION=Miscellaneous
CATEGORY=Civilized</spherescript>

As you can see, it doesn't look a lot different than the item scripts we examined in the previous section. There are a lot of variables set that are the same, including DEFNAME, DESCRIPTION, and the other Axis variables.

But, there are a lot of new things here that we will again go over, one line at a time! And it's longer this time! Let the good times roll! (Sorry if you're not American.. All my American clichés are probably growing irritating!)

'''Line 1''': [CHARDEF 0190]

Surprise surprise! It's an identifier, telling the server that we are going to be defined a character between this and the next [identifier]. And we also tell it that our character, or NPC, will have the ID 0190. The server knows that this ID is one of the built-in IDs. In fact, it's the ID of a naked man. You also know that 0190 is hexadecimal is 400 in decimal right? :) Well why didn't you know that! Oh I'm just kidding, you don't need to know things like that.

'''Line 2''': DEFNAME=c_man

Nothing new here. c_man is now the same as 0190. Most character DEFNAMEs will begin with C and then an underscore (c_) like you see above.

'''Line 3''': Name=Man

Oh oh! Something new! Items come with default names, built in to the server. Characters don't. So we have to assign him a name. We can give him any name we want, but since this isn't a specific man, we just give him a name telling us what he is. In this case "Man".

'''Line 4''': ICON=i_pet_man

It took me a while to figure this one out. ICON defines what little picture you see when you're using the Tracking skill and all those little miniature creatures appear in the window. Those are actually items, all the i_pet items. To find out what the i_pet item for your creature should be, create him in the game using .addnpc, then use the .shrink command on him. The ID of the item that he becomes is your i_pet item.

'''Line 5''': CAN=mt_*

(In case you don't know, * means "anything" for those who use Linux.)

This is one of the most important lines of your character script, next to the ID we give him in the first line. First, because it allows us to tell the game what our NPC can do and what he can't do. There are only a few mt_* items, all of which are defined in spheredefs.scp. For the purpose of the lesson, I am going to copy them here. (The purple comments are mine.)

<spherescript>MT_NONMOVER 0 // We can't move at all
MT_GHOST 01 // We can walk through doors and such, like a ghost
MT_SWIM 02 // I can swim! (Water elementals, dolphins, etc)
MT_WALK 04 // I can move. Set this if you want your creature to move.
MT_FLY 010 // Moves through (supposed to be over) trees
MT_FIRE_IMMUNE 020 // Immune to damage by fire. Setting this on a player is bad. :)
MT_EQUIP 00100 // Can equip things
MT_USEHANDS 00200 // Can use his hands to carry things (or open doors)
MT_MALE 0 // Is a male
MT_FEMALE 00800 // Is a female
MT_NONHUM 01000 // Non-human. I'm not sure what this does.
MT_RUN 02000 // Can move really fast!</spherescript>

According to this chart, we can see that if we don't give a creature a CAN flag, it will be an MT_MALE and an MT_NONMOVER (the two zeros). You can see from the example that by putting a | (found by pressing shift+backslash) between two CAN flags, we can give him more than one. In this case, we allow our man to equip things, walk, run, and use his hands. (An interesting fact is, even creatures that don't have hands can be set to use their hands, thus allowing them to carry light sources. Fire elementals do this. That's how they glow.)

'''Line 6''': RESOURCES

Resources is a very morbid name for this setting. Especially for a person. These are the items that you get whenever you chop up this creature's corpse. Scary eh? :)

'''Line 7-10''': FOODTYPE, DESIRES, AVERSIONS

'''FOODTYPE''': Defines what kind of food the npc will eat and if NPC_AI_FOOD is on it'll make the npc look for this food + grass when he's hunger.

'''DESIRES''': Defines what kind of items will the npc be interested in, if NPC_AI_EXTRA is on it'll show what items the npc will loot of players corpses or walk towards when it's on the ground.

'''AVERSIONS''': No idea, but I think it tells the npc what sort of NPCs he'll try to fight, for example: I have a horse with e_horse as an event, and an imp without any events, if the npc has AVERSIONS=e_horse it'll prefer to fight the horse.

'''Line 11''': BLOODCOLOR

Ever wanted to make your players have green blood? This is where you do it! A color number or a color defname will work fine. (Try to learn the numbers for common colors, it makes it so much easier.)

The rest of it: TSPEECH and TEVENTS

We're going to cover these in sections of their own. They are probably the most complex topics in scripting! (How many times do you suppose I'm going to say that before it's actually true?)

''<font color="darkblue">Some other things:</font>''

On 56B we have some other fields like MOVERATE,RESLEVEL,RESDISPDNID and RESDISPDNHUE. They sound some difficult and strange thing but they aren't. Here's the explanation for them:

'''MOVERATE''': This setting (that can only be writed at the npc chardef) controls how fast the npc moves. The smaller the value, the faster the npc is. For example, if I have a horse chardef with default moverate (100) and another with moverate=60, the one with 60 will walk and run a lot faster than the other horse. This is great for making really difficult monsters to kill.

'''RESLEVEL''': This tells sphere what version of uo this monster is from, for example, a Wanderer of the Void will have RESLEVEL=3 (3=AOS) (see sphere_defs.scp for a complete list), so only accounts with RESDISP 3 or bigger can see this monster as he really is.

''NOTE'': If you set a lower value for RESLEVEL, if the player doesn't have this npc anim he'll crash.

'''RESDISPDNID''': As you probably have seen, I used a lot of "as he really" is, exactly because of this setting, this tells the client what monster will the player see instead of the correct one. For example, this Wanderer of the Void will show as Wanderer of the Void for those who has ACCOUNT.RESDISP=3 or bigger, but for those who has smaller values it'll show as a c_spectre (if you so define).

'''RESDISPDNHUE''': This defines what color will the player see the monster if the RESDISPDNID id is shown to him (have an account.resdisp lower than the reslevel of this char)

Here's an example for those new settings:

<spherescript>[CHARDEF 310]
DEFNAME=c_Wailing_Banshee
NAME=Wailing Banshee
SOUND=snd_monster_zombie1
ICON=i_pet_wailingbanshee
DAM=11,16
RESDISPDNID=c_spectre
RESLEVEL=3
RESDISPDNHUE=01
ARMOR=20
CAN=MT_WALK|MT_FLY
DESIRES=i_gold,e_notoriety,e_horses,c_man,c_woman,t_corpse
CATEGORY=New Monsters
SUBSECTION=AOS
DESCRIPTION=Wailing Banshee

ON=@Create
NPC = brain_monster
FAME = {100 3000}
KARMA = {-5000 -6999}
STR = {126 166}
INT = {86 115}
DEX = {41 75}
MAGICRESISTANCE = {75.0 95.0}
TACTICS = {45.0 75.0}
WRESTLING = {50.0 70.0}

ON=@NpcRestock
ITEM = i_gold, {50 100}
ITEM = i_reag_daemon_bone, {2 6}</spherescript>

And there you have it. A simple character script and some new things. Read the chapter that is all about making NPCs later in the tutorial.

==TEMPLATE==
Or, how to put great laggy quantities of items into one unlaggy container.

You've all seen it. Those shards out there that don't use TEMPLATEs. When you kill, say, a dragon, on those shards, and go to loot him, you find that rather than neatly organized containers, there are 100 potions scattered about the loot window. Not only that, but all your magical weapons are buried neatly beneath them!

How do we solve this problem? Well, SPHERE has given us the handy tool of TEMPLATEs. These allow you to define a container item, AND the items inside of it, AT THE SAME TIME. Isn't that neat? I thought so too, when I first figured out what they were. Let's do our traditional take-apart-the-script section. I'll place a nice TEMPLATE from the file spheretemp_loot.scp.

<tt><font color="darkblue">[TEMPLATE 101505]<br />
DEFNAME=backpack_poor<br />
CATEGORY=Item Templates<br />
SUBSECTION=Loot Templates<br />
DESCRIPTION=Poor Backpack<br />
CONTAINER=i_backpack<br />
ITEM={ random_food 1 0 3 },{ 1 3 }<br />
ITEM={ random_bottle 1 0 8 }<br />
ITEM={ random_light 1 0 8 }<br />
ITEM={ random_male_tops 1 0 4 }<br />
COLOR=colors_all<br />
ITEM={ random_male_pants 1 0 4 }<br />
COLOR=colors_all<br />
ITEM=POOR_GOLD_PILE<br /></font></tt>

Wow, that looks confusing. But don't worry, by the time we're done, you'll know exactly what it means!

<font color="darkblue">[TEMPLATE 101505]</font>: First of all, we look at the header for our template. An interesting thing about templates is that the item name cannot be a DEFNAME like all other scripts. It must be a ridiculously high number like 101505.
<font color="darkblue">DEFNAME=backpack_poor</font>: Of course, SPHERE developers are not entirely evil, and have provided us with the ability to give these scary numbers a DEFNAME for easier access. You tell me, which would you rather type? ".add 101505" or ".add backpack_poor"? I thought so.

'''Note:''' Since .56c, move DEFNAME to [TEMPLATE ...], e.g. [TEMPLATE backpack_poor]

<font color="darkblue">CATEGORY, SUBSECTION, DESCRIPTION</font>: Axis crap. Optional. See the previous sections for a description of what these do.

<font color="darkblue">CONTAINER=i_backpack</font>: Ahh, now we're getting down to the meat of this thing. This specifies the holding container that all other items in this template will be in. When you add the item in game, you will see this container. In this case, it's a backpack. Simple enough. This can be any valid item with a TYPE of t_container or t_container_locked.

<font color="darkblue">ITEM={ random_food 1 0 3},{1 3}</font> Well, that's certainly cryptic. I think we need to break this line down even further.

But first, we're going to cover RANDOM SELECTORS! Sounds like fun doesn't it? Nah, it doesn't sound fun to me either, but it's absolutely necessary to a good shard.

Basically, they are an easy way to get different numbers with one command. What fun would a shard be where you killed a dragon and got a Platemail of Magic Stuff and a Super Duper Sword of Power every single time? Everyone would be running around with them. What we need is some variety!

There are two types of random selectors: weighted random and ranged random. Weighted random makes a statement like this: "Ok, 1 out of 10 times pick Number A, 3 out of 10 times pick Number B, and 6 out of 10 times pick number C". Ranged random makes a statement like this: "Pick any number between the two numbers I give you".

Our example actually has an example of both ranged random and weighted random. We'll cover them in the order they appear:

{ random_food 1 0 3}

This is a weighted random selector. The way to interpret these is to take the numbers that appear between the parentheses and divide them into sets of two:

random_food 1<br>
0 3

Add up the second numbers in both sets, and we get 4. This tells SPHERE, "Ok, 1 out of four times, I want you to pick random_food, and 3 out of four times, I want you to pick zero." You can even have random sets within random sets, but then it just gets confusing.

{ { random_food 1 0 3} 1 random_clothing 1}

Can you figure it out?

random_clothing 1
{ random_food 1 0 3} 1

2 is our magic number in this case. One out of two times, SPHERE will pick random_clothing, and one out of two times, SPHERE will pick our previous random selector, which will then select one of its own options. If you're confused at this point, don't worry. This is extremely rare, and we'll see in a moment how templates help us to solve this problem.

I did mention, though, that there is another type of random selector, and you can probably see what it is:

{1 3}

NOTE: Spacing here is important. There must be ZERO spaces between the { and the first number, or the } and the last number. It will behave strangely otherwise.

This tells SPHERE "Pick a number between 1 and 3, inclusive". Inclusive means that SPHERE can pick 1, 3, or any number in between. In this case, the range is rather limited. SPHERE will give you a 1, 2 or 3 here. Ranged random selectors are actually more often used inside of weighted random selectors.

{ {1 3} 3 {4 9} 1}

"One out of four times, pick a number between 4 and 9. Three out of four times, pick a number between 1 and 3."

And with that out of the way, we're going to analyze the actual line of the script from above. The Piece What the Line does ITEM=
This tells the script "Ok, we're going to add an item to this container. Anything after the = tells the script exactly what it is we're adding and in what amounts. You could easily say ITEM=i_platemail_chest, or something like that, without the mysterious { } sections, but the reason templates are interesting is because they can vary greatly.

<font color="darkblue">{ random_food 1 0 3}</font>

This is the item you will be creating. As we can see from our weighted random selector lesson, 1 out of 4 times, it will be random_food, and 3 out of 4 times, it will be zero. If an ITEM is zero, nothing will be created this time. Basically this is saying "There will be a one in four chance of getting random_food in this container." What is random_food you ask? Well, it happens to be another TEMPLATE, defined in spheretemplate.scp, I believe.

{1 3} This is the amount of the item that will be created. You should recognize this as a ranged random selector. This tells SPHERE to put between 1 and 3 of this item into the container. Of course, if the item is zero as selected above, this has no effect since one nothing and three nothings are still nothing.

So basically, that is a template script. You then fill it with as many items as you want. You may also notice the following construction:

ITEM=i_sword_long,R11

This is a shorthand way of writing this:

ITEM={ i_sword_long 1 0 10 }

R11 means "one out of 11 chance of finding this item". And you can add an amount selector to the end of that as well, which makes it look long and scary:

ITEM=i_sword_long,R11,{4 5}

But why would you want 4 or 5 long swords in one item? That would be bizzare. :)

And that's about it for templates. Congratulations, you're finished with chapter 1. Now you should be able to understand the examples to follow on the next section. You may also have some questions which are addressed in the common questions area. If you have a question which is not addressed there, perhaps it is too advanced of a topic for chapter 1. I assure you almost every aspect of SPHERE scripting will be covered in later chapters.

''(A template example by Belgar)''

<tt><font color="darkblue">[TEMPLATE tm_necromancer]<br />
CONTAINER=i_bag<br />
ITEM=random_necro_scroll<br />
ITEM=random_necro_scroll<br />
ITEM=random_necro_reagent, {5 12}<br />
ITEM=random_reagent, {5 12}<br />
ITEM=random_necro_reagent, {5 12}<br /></font></tt>

==Examples==
Or, um. Well I guess there really isn't another way to say "Examples".

This shall be my attempt to create the most basic new items available. You will see things in these examples that are NOT mentioned in the tutorials. The major factor will be ON=@Create, which is the primary topic of Chapter 2. Just know for now that things you can change in game (color, etc) must go under ON=@Create.

'''Example 1''': A Red Sword

<tt><font color="darkblue">[ITEMDEF i_sword_red]<br />
ID=i_sword_viking<br />
TYPE=t_weapon_sword<br />
NAME=The Red Sword<br />
CATEGORY=Weapons<br />
SUBSECTION=New Swords<br />
DESCRIPTION=Red Sword<br />

ON=@Create
:COLOR=colors_red // This is a comment. Comments are ignored by SPHERE.<br /></font></tt>

Wait, what is this weird <font color="darkblue">//</font> thing we've got going here? That's called a comment. It's completely ignored by SPHERE, so you can write whatever you want to the end of the line after //. You cannot have multi-line comments in SPHERE unless you use a new //, so don't even try it. SPHERE will give funky errors and then you'll have fun finding them.

'''Example 2''': A blue ettin

<tt><font color="darkblue">[CHARDEF c_ettin_blue]<br />
ID=02 // You could just as easily use c_ettin here.<br />
NAME=My Blue Ettin<br />
<br />
<br />
ON=@Create<br />
:COLOR=02 // This is a dark blue color. It's often used for Counselor robes. Remember it.<br /></font></tt>

'''Example 3''': A template from the file, since I'm too lazy to write one myself

<tt><font color="darkblue">[TEMPLATE 101521]<br />
DEFNAME=goodie_meager_1<br />
CATEGORY=Item Templates<br />
SUBSECTION=Loot Templates<br />
DESCRIPTION=Meager Goodie 1<br />
ITEM={ meager_gold_pile 1 backpack_meager 1 pouch_meager 1 }<br />
ITEM={ random_boots 1 0 4 }<br />
ITEM={ random_gorget 1 0 4 }<br />
ITEM={ random_staff 1 0 4 }<br />
ITEM={ random_necklace 1 0 4 }<br />
ITEM={ i_cape 1 0 9 }<br />
<font color="darkred">COLOR=colors_all</font><br /></font></tt>

You may notice something new here (especially since I highlighted it in red), and yes, it is legal. Any lines between ITEM= lines will affect the previously created item. The COLOR= line here affects the ITEM created by the line

ITEM={ i_cape 1 0 9 }

Remember, the best way to learn this type of scripts is to read the scripts provided for you in files like sphereitem_colorarm.scp and sphereitem_beers.scp.

[[Category:Tutorials]]

Chapter 1

2022-08-19T19:21:20Z

Soulless:

{{Languages|Chapter_1}}

==Numbers==

The first thing you'll notice while looking through SPHERE scripts is the wide variety of ways to write numbers. Since numbers are insanely important to a SPHERE scripter, this is the first lesson in the series. By the end of the lesson, I hope that you have a general understanding of hexadecimal, decimal and binary numbering systems, and SPHERE's ways of identifying each. You will also know how to generate random numbers either from a series or from a list of choices.

The first thing you need to understand is that the way we count is not the only way to count. Our numbering system contains ten digits (0, 1, 2, 3, 4, 5, 6, 7, 8, and 9). Therefore, at the tenth number, we have to add an extra column to the number, and reset the first column to zero (1, 2, 3, 4, 5, 6, 7, 8, 9, 10). That's why our numbering system works the way it does.

In the decimal system, without realizing it, we write our numbers to mean powers of ten. For example, if you take the number 17282 (which I just made up), and divide it down we get this:

{| border="1"
| Power of ten || 4 || 3 || 2 || 1 || 0
|-
| Ten to that power || 10000 || 1000 || 100 || 10 || 1
|-
| Digit || 1 || 7 || 2 || 8 || 2
|}

To reach the number 17282 from here, we simply take ten to the power of the number in the top row, multiply it by the number in the bottom row, and then add all those numbers together. We get 10000 + 7000 + 200 + 80 + 2. Obviously, this is simplistic, and we do it without even realizing we're doing it. You're probably thinking "Riiight, what does Taran think he's getting at?" Well, we aren't so special that our counting system is the only way to count.

Now, there is another numbering system that is used almost solely by computers. It only contains two numbers (1 and 0) and is therefore called the binary (meaning two) system. Binary numbers look like this: 101011101101, and you often see them in ads for computers and other electronic equipment (oftentimes they are shown streaming out of a CD player on television commercials). Digits in the binary system are called bits (short for BInary digiT)Binary numbers are almost impossible to translate to decimal directly, and so some math must be done.

Binary works in the same way, by adding powers of a number. In the case of binary, since there are two numbers in the whole system, that number is naturally two. Here are some examples of powers of two. These numbers might look familiar to some people.

{| border="1"
| Power of 2 || Binary number || Decimal number
|-
| 0 || 1 || 1
|-
| 1 || 10 || 2
|-
| 2 || 100 || 4
|-
| 3 || 1000 || 8
|-
| 4 || 10000 || 16
|-
| 5 || 100000 || 32
|-
| 6 || 1000000 || 64
|-
| 7 || 10000000 || 128
|-
| 8 || 100000000 || 256
|-
| 9 || 1000000000 || 512
|-
| 10 || 10000000000 || 1024
|}

Ridiculous eh? :)

We need a better system! The reason we get such strange results is because 10 is not a power of two. We need to find a system where the number base IS a power of two. The most commonly used system used is base-16, or hexadecimal. I'm sure if you've perused the SPHERE boards, you've seen the word hex floating around. No, this isn't a curse or evil spell, it's a short way of saying "hexadecimal".

{| border="1"
| Binary || Decimal || Hexadecimal
|-
| 1 || 1 || 1
|-
| 10 || 2 || 2
|-
| 11 || 3 || 3
|-
| 100 || 4 || 4
|-
| 101 || 5 || 5
|-
| 110 || 6 || 6
|-
| 111 || 7 || 7
|-
| 1000 || 8 || 8
|-
| 1001 || 9 || 9
|-
| 1010 || 10 || A
|-
| 1011 || 11 || B
|-
| 1100 || 12 || C
|-
| 1101 || 13 || D
|-
| 1110 || 14 || E
|-
| 1111 || 15 || F
|-
| 10000 || 16 || 10
|}

See how it works? There are an extra six numbers added onto the end of the system, represented by the first six letters of the alphabet.

Now, in SPHERE scripting, you are almost NEVER going to be dealing with binary numbers that are NOT powers of two, and if you do, you can simply use any scientific calculator to figure it out. But it's a lot easier in hexadecimal.

(This is the last table, I promise!!)
{| border="1"
| Binary || Hexadecimal
|-
| 000000001 (1) || 01
|-
| 000000010 (2) || 02
|-
| 000000100 (3) || 04
|-
| 000001000 (4) || 08
|-
| 000010000 (5) || 010
|-
| 000100000 (6) || 020
|-
| 001000000 (7) || 040
|-
| 010000000 (8) || 080
|-
| 100000000 (9) || 0100
|}

As you can see, there's a bit of a pattern in the hexadecimal column. You might be thinking, there seems to be some sort of pattern of the numbers 1, 2, 4 and 8. And you would be right. Another detail you may notice is the zeros in front of the hexadecimal numbers (like 0100, rather than just 100). In SPHERE, that 0 tells the script "Hey, this number is HEX!" 0100 and 100 are very different numbers.

Let's say, for a SPHERE script, you need to set the 13th bit of a number (FLAGS, for example), you could write something like this:

'''SRC.FLAGS |= 8192'''

But would you really remember that 8192 is 2 to the 13th power? I didn't think so. What would be easier is to go down through your list in your head, until you reach the 13th number. (Remember, START AT ZERO when you're counting!)

{| border="1"
| 01 || 02 || 04 || 08 || 010 || 020 || 040 || 080 || 0100 || 0200 || 0400 || 0800 || 01000 || 02000
|-
| 2^0 || 2^1 || 2^2 || 2^3 || 2^4 || 2^5 || 2^6 || 2^7 || 2^8 || 2^9 || 2^10 || 2^11 || 2^12 || 2^13
|}

And there you have it. The first 14 powers of two in hexademical.

'''SRC.FLAGS |= 02000'''

The above code is identical to the previous example. 8192 (decimal) is EQUAL to 02000 (hexadecimal)

'''8192 = 02000'''

You may be saying, "How do I know he's just not making all of this up?" Well, our wonderful friends at Microsoft have provided us with a nice tool that converters from decimal to hexadecimal to binary to octal (ANOTHER numbering system that is useless in SPHERE, so we will not deal with it). It's called the Calculator. You may find it by clicking your start button, going to Programs, then Accessories. Calculator should be sitting there looking pretty. Once in the calculator program, go to the View menu, and click Scientific. You'll see the display drastically change. To convert a number between numbering systems, simply click on the original system (Dec), type a number (8192), then click on the button for the other system (Hex). Automagically, Windows will convert your decimal number to hexadecimal. Stick a zero on the front, and SPHERE will be perfectly happy with it.

This is probably the hardest thing in all of SPHERE scripting to understand. Luckily, because of the next section, you won't have to deal with scary numbers most of the time. If I still have you at the end of this lesson, I know you're going to do great!

Onward to some SPHERE scripting!

==Defnames==

Here's a list of scary numbers you might encounter while programming in SPHERE.

{| border="1"
| The Scary Number || What it means
|-
| 0eed || ID of a gold coin
|-
| 0dda || ID of a red moongate
|-
| 1650,1440 || Coordinates of Britain
|-
| 021 || The code number for red
|-
| 04000 || The invisible color
|-
| 04000efad || An item's serial number
|-
| 4 || The PLEVEL of a GM
|-
| 2048 (or 0800) || Flag for incognito spell
|-
| 010 (or 16) || Memory type for aggressors
|}

Obviously, no one is going to want to remember those numbers. Back in the old days, before SPHERE and TUS (pre-.50 SPHERE) and even into the mists of Grayworld (pre-.41 TUS), we all had to remember those numbers. I know all of those numbers I just said (except the serial number which I just made up), plus a couple dozen more, by heart. Luckily for those of you who don't like to sit around remembering numbers all day, SPHERE has developed a system whereby things can be identified by names instead of numbers.

Actually, the things are still identified by numbers. It's the numbers which are identified by the name.

In the game, type .add 0eed and press enter. A target will come up and you'll create a single gold piece.

Now type .add i_gold and press enter. You will create the same single gold piece.

Now which is easier to remember, 0eed or i_gold. I would say that i_gold wins by a long shot. But how does this magic happen? Let's take a look at the script definition for a piece of gold. Don't worry about understanding it. I'll explain item scripts in full in the next section! You can find this script in the file sphere_item_resources.scp.

<tt><font color="darkgreen">[ITEMDEF 0eed]<br />
//gold coin<br />
<font color="ff0000">DEFNAME=i_gold</font><br />
TYPE=T_GOLD<br />
VALUE=1<br />
CATEGORY=Provisions - Miscellaneous<br />
SUBSECTION=Coins<br />
DESCRIPTION=Gold Coin<br />
DUPELIST=0eee,0eef</font><br /></tt>

I have highlighted in red the line that really matters for the purposes of this lesson. Take note of the 0eed in the top line of the script, and then ignore the rest of it. That 0eed is the real item number of this item. We'll cover item numbers more in the next section.

But the real line we want to see the <font color="ff0000">DEFNAME=i_gold</font> line. This is where the script tells the server, "I want item 0eed to be identified by the text i_gold from here on." If you tried to refer to i_gold before the server read this script (more on reordering scripts in [[Chapter 2]], the server would spit out an error, but now it knows what that refers to, so you can use it in the game or in another script.

You should ALWAYS give items you create a DEFNAME that fits the item. Usually the defname will be defined in the [ITEMDEF] identifier itself (again, more on this later), but if you insist upon using numbers, be sure you give it an easy-to-remember name (not golden_gulash for a viking sword). It makes it easier to remember names than numbers.

A second way to define a DEFNAME is by using the [DEFNAME] tag in a script. Here is an example of that:

<tt><font color="darkgreen">[DEFNAME colors]<br />
color_blue 02<br />
color_red 021<br />
color_green 041</font><br /></tt>

You'll find a script similar to this in spheredefs.scp, another file that should be loaded before any other file.

Here's the rundown on this script, line by line:

'''Line 1''': This is where the type of script and the defname (yes colors is the defname of this script) is defined. This tells the server what type of script to expect between this and the next identifier (identifiers are the lines contained in square brackets). All identifiers have this format. The first parameter is the script type. These are numerous, and I will go over them as we get to them. The second parameter is either an ID number or a defname. In most cases, in the scripts you write, it will be a defname. The only exceptions to this I can think of would be if you used a program to insert a new item into the client files.

'''Lines 2-4''': These set up your individual DEFNAME pieces. It says that color_blue is equal to 02, color_red is equal to 021, and color_green is equal to 041. You may have any number of spaces between the name and the value. The definitions contained in spheredefs.scp are among the most useful you will encounter, as they prevent you from writing the long scary numbers we went over in the previous section. These include things like names for flags, names for item attributes, names for the built-in MIDI or MP3 music, names for memory types, and many other things. Look through the file to see what it offers you.

That's about it for DEFNAMEs. You'll see more of these later as we cover other types of scripts.

Now go on to learn about items.

==ITEMDEF==
Or, how to make a mountain from a molehill, SPHERE style

Most people make item scripting much harder than it needs to be. For the purposes of this tutorial, since there is a more advanced one later, we will simply go over the basics of an ITEM script, line by line. We'll be using the gold script from the previous lesson, provided I can find it again....

Ah, here it is, conveniently color coded for your viewing pleasure!

<spherescript>[ITEMDEF 0eed]
//gold coin
DEFNAME=i_gold
TYPE=T_GOLD
VALUE=1
CATEGORY=Provisions - Miscellaneous
SUBSECTION=Coins
DESCRIPTION=Gold Coin
DUPELIST=0eee,0eef</spherescript>

This is the simplest of item scripts, since it has no additional behaviors beyond existing. I will go through this line by line, describing to you what each line does, and how it affects the end result.

'''Line 1''': [ITEMDEF 0eed]

The first lines of an item script are frequently the most important. Basically, this line tells the server "Hey this is an item and I want it to be called 0eed!" The server then looks through one of the client files (specifically art.idx), and identifies whether or not this item is one of the built-in items. I think all items below 04500 are defined as built-in items, so never define a new item in that range. By typing this line, you tell the server that an item script is following. You also define 0eed as a valid item, which will definitely help later on when you try to give gold to players!

'''Line 2''': // gold coin

This is the SPHERE version of comment. C programmers will recognize the format immediately. If you type // on any line of code, everything beyond that is ignored by the script reader. This can be on a line by itself, or at the end of a line to explain what the specific line does. In all cases, it won't affect your program, just make it easier to read.

'''Line 3''': DEFNAME=i_gold

You should know by now what this does! If you don't, go back and read the previous lesson! It tells the server that i_gold and 0eed mean the same thing. In item scripts, all parameters are defined in that format:

variable=value

You will see later on, when we get into scripting, how that format will help you more than you would believe. Items have a good number of variables that you can define, including:

* DEFNAME
* ID
* TYPE
* VALUE
* RESOURCES
Other variables depend on the value of the TYPE. Which leads us right into...

'''Line 4''': TYPE=t_gold

The first thing you might say is "What the heck is t_gold?" Well it's a DEFNAME. Actually it's a number. And that number is 72. If you want to check me on this, look in spheredefs.scp, it's there! Writing TYPE=72 would have the exact same effect.

There are, currently, 183 built-in item types. These are hardcoded item types that contain predefined actions for an item. If an item has no type, when you click it, you get the "You cannot think of a way to use that item" message. There is a complete list of types, and how to set them up, here . All you need to know for now is that setting the type of this item to t_gold has no effect other than to make the item act like a gold coin (i.e. you can buy stuff with it!) Setting another item to type t_gold would probably make the server think that you can buy stuff with that item too. I've never tried this. It might be an interesting way to have unique currencies...

'''Line 5''': VALUE=1

This defines how much the item costs when purchased, in gold. Of course, this is one gold piece, which is worth, well, one gold piece. So the value of the item is one.

'''Lines 6-8''': CATEGORY, SUBSECTION, DESCRIPTION

These are lines used only by SPHERE's GM tool, Axis, which actually saves you a lot of work by typing ".add i_gold" for you. More importantly, it types ".add 01737" and things like that for you, for items that were not important enough to get their own separate DEFNAME.

'''Line 9''': DUPEITEM

It would be a ton of work for the SPHERE team to define all 8000 items that came with the game, especially when many of them are the same. (For an example of this, use the .xflip command on a door or sign. It cycles through all of the DUPEITEMs for that the item being flipped.) The numbers listed here are item numbers, which probably have not been defined yet. Here is the script for item 0eee:

<spherescript>[ITEMDEF 0eee]
//gold coins
DUPEITEM=0eed
CATEGORY=Provisions - Miscellaneous
SUBSECTION=Coins
DESCRIPTION=Gold Coins</spherescript>

As you can see, there is only one parameter for this whole item. It reiterates the DUPEITEM and sends the server looking to our 0eed (or i_gold) item for more information, such as TYPE and VALUE. DUPEITEM only exists to save typing. You probably won't use it.

==CHARDEF==
Or, what it takes to make a naked man who can stand around and say "Huh?"

NPCs... They make the world go around. They are what makes UO a unique multiplayer game. The monsters and NPCs you create make your server unique from any other. This section of chapter one will cover how to create a simple naked man who walks around and says little more than "Huh?" (or "Stop thief!" if you tell him to!).

First of all, we'll look at the script for a simple naked man. I'm pulling this out of spherechar_human.scp.

<spherescript>[CHARDEF 0190]
DEFNAME=c_man
Name=Man
ICON=i_pet_MAN
CAN=MT_EQUIP|MT_WALK|MT_RUN|MT_USEHANDS
RESOURCES=i_flesh_head, i_flesh_torso, i_flesh_right_arm, i_flesh_left_arm
FOODTYPE=15 t_food, t_fruit
DESIRES=i_gold,e_notoriety
AVERSIONS=t_TRAP,t_eerie_stuff
SHELTER=r_house
BLOODCOLOR=0

TSPEECH=spk_human_prime
TSPEECH=spk_human_default
TEVENTS=e_Human_HearUnk
DESCRIPTION=Man
SUBSECTION=Miscellaneous
CATEGORY=Civilized</spherescript>

As you can see, it doesn't look a lot different than the item scripts we examined in the previous section. There are a lot of variables set that are the same, including DEFNAME, DESCRIPTION, and the other Axis variables.

But, there are a lot of new things here that we will again go over, one line at a time! And it's longer this time! Let the good times roll! (Sorry if you're not American.. All my American clichés are probably growing irritating!)

'''Line 1''': [CHARDEF 0190]

Surprise surprise! It's an identifier, telling the server that we are going to be defined a character between this and the next [identifier]. And we also tell it that our character, or NPC, will have the ID 0190. The server knows that this ID is one of the built-in IDs. In fact, it's the ID of a naked man. You also know that 0190 is hexadecimal is 400 in decimal right? :) Well why didn't you know that! Oh I'm just kidding, you don't need to know things like that.

'''Line 2''': DEFNAME=c_man

Nothing new here. c_man is now the same as 0190. Most character DEFNAMEs will begin with C and then an underscore (c_) like you see above.

'''Line 3''': Name=Man

Oh oh! Something new! Items come with default names, built in to the server. Characters don't. So we have to assign him a name. We can give him any name we want, but since this isn't a specific man, we just give him a name telling us what he is. In this case "Man".

'''Line 4''': ICON=i_pet_man

It took me a while to figure this one out. ICON defines what little picture you see when you're using the Tracking skill and all those little miniature creatures appear in the window. Those are actually items, all the i_pet items. To find out what the i_pet item for your creature should be, create him in the game using .addnpc, then use the .shrink command on him. The ID of the item that he becomes is your i_pet item.

'''Line 5''': CAN=mt_*

(In case you don't know, * means "anything" for those who use Linux.)

This is one of the most important lines of your character script, next to the ID we give him in the first line. First, because it allows us to tell the game what our NPC can do and what he can't do. There are only a few mt_* items, all of which are defined in spheredefs.scp. For the purpose of the lesson, I am going to copy them here. (The purple comments are mine.)

<spherescript>MT_NONMOVER 0 // We can't move at all
MT_GHOST 01 // We can walk through doors and such, like a ghost
MT_SWIM 02 // I can swim! (Water elementals, dolphins, etc)
MT_WALK 04 // I can move. Set this if you want your creature to move.
MT_FLY 010 // Moves through (supposed to be over) trees
MT_FIRE_IMMUNE 020 // Immune to damage by fire. Setting this on a player is bad. :)
MT_EQUIP 00100 // Can equip things
MT_USEHANDS 00200 // Can use his hands to carry things (or open doors)
MT_MALE 0 // Is a male
MT_FEMALE 00800 // Is a female
MT_NONHUM 01000 // Non-human. I'm not sure what this does.
MT_RUN 02000 // Can move really fast!</spherescript>

According to this chart, we can see that if we don't give a creature a CAN flag, it will be an MT_MALE and an MT_NONMOVER (the two zeros). You can see from the example that by putting a | (found by pressing shift+backslash) between two CAN flags, we can give him more than one. In this case, we allow our man to equip things, walk, run, and use his hands. (An interesting fact is, even creatures that don't have hands can be set to use their hands, thus allowing them to carry light sources. Fire elementals do this. That's how they glow.)

'''Line 6''': RESOURCES

Resources is a very morbid name for this setting. Especially for a person. These are the items that you get whenever you chop up this creature's corpse. Scary eh? :)

'''Line 7-10''': FOODTYPE, DESIRES, AVERSIONS

'''FOODTYPE''': Defines what kind of food the npc will eat and if NPC_AI_FOOD is on it'll make the npc look for this food + grass when he's hunger.

'''DESIRES''': Defines what kind of items will the npc be interested in, if NPC_AI_EXTRA is on it'll show what items the npc will loot of players corpses or walk towards when it's on the ground.

'''AVERSIONS''': No idea, but I think it tells the npc what sort of NPCs he'll try to fight, for example: I have a horse with e_horse as an event, and an imp without any events, if the npc has AVERSIONS=e_horse it'll prefer to fight the horse.

'''Line 11''': BLOODCOLOR

Ever wanted to make your players have green blood? This is where you do it! A color number or a color defname will work fine. (Try to learn the numbers for common colors, it makes it so much easier.)

The rest of it: TSPEECH and TEVENTS

We're going to cover these in sections of their own. They are probably the most complex topics in scripting! (How many times do you suppose I'm going to say that before it's actually true?)

''<font color="darkblue">Some other things:</font>''

On 56B we have some other fields like MOVERATE,RESLEVEL,RESDISPDNID and RESDISPDNHUE. They sound some difficult and strange thing but they aren't. Here's the explanation for them:

'''MOVERATE''': This setting (that can only be writed at the npc chardef) controls how fast the npc moves. The smaller the value, the faster the npc is. For example, if I have a horse chardef with default moverate (100) and another with moverate=60, the one with 60 will walk and run a lot faster than the other horse. This is great for making really difficult monsters to kill.

'''TAG.OVERRIDE.MOVEDELAY''': Overrides completely the moverate checks and setting the next movement to the given timer, eg 'tag.override.moverate=250' makes the npc move each 250 milliseconds when walking.

'''RESLEVEL''': This tells sphere what version of uo this monster is from, for example, a Wanderer of the Void will have RESLEVEL=3 (3=AOS) (see sphere_defs.scp for a complete list), so only accounts with RESDISP 3 or bigger can see this monster as he really is.

''NOTE'': If you set a lower value for RESLEVEL, if the player doesn't have this npc anim he'll crash.

'''RESDISPDNID''': As you probably have seen, I used a lot of "as he really" is, exactly because of this setting, this tells the client what monster will the player see instead of the correct one. For example, this Wanderer of the Void will show as Wanderer of the Void for those who has ACCOUNT.RESDISP=3 or bigger, but for those who has smaller values it'll show as a c_spectre (if you so define).

'''RESDISPDNHUE''': This defines what color will the player see the monster if the RESDISPDNID id is shown to him (have an account.resdisp lower than the reslevel of this char)

Here's an example for those new settings:

<spherescript>[CHARDEF 310]
DEFNAME=c_Wailing_Banshee
NAME=Wailing Banshee
SOUND=snd_monster_zombie1
ICON=i_pet_wailingbanshee
DAM=11,16
RESDISPDNID=c_spectre
RESLEVEL=3
RESDISPDNHUE=01
ARMOR=20
CAN=MT_WALK|MT_FLY
DESIRES=i_gold,e_notoriety,e_horses,c_man,c_woman,t_corpse
CATEGORY=New Monsters
SUBSECTION=AOS
DESCRIPTION=Wailing Banshee

ON=@Create
NPC = brain_monster
FAME = {100 3000}
KARMA = {-5000 -6999}
STR = {126 166}
INT = {86 115}
DEX = {41 75}
MAGICRESISTANCE = {75.0 95.0}
TACTICS = {45.0 75.0}
WRESTLING = {50.0 70.0}

ON=@NpcRestock
ITEM = i_gold, {50 100}
ITEM = i_reag_daemon_bone, {2 6}</spherescript>

And there you have it. A simple character script and some new things. Read the chapter that is all about making NPCs later in the tutorial.

==TEMPLATE==
Or, how to put great laggy quantities of items into one unlaggy container.

You've all seen it. Those shards out there that don't use TEMPLATEs. When you kill, say, a dragon, on those shards, and go to loot him, you find that rather than neatly organized containers, there are 100 potions scattered about the loot window. Not only that, but all your magical weapons are buried neatly beneath them!

How do we solve this problem? Well, SPHERE has given us the handy tool of TEMPLATEs. These allow you to define a container item, AND the items inside of it, AT THE SAME TIME. Isn't that neat? I thought so too, when I first figured out what they were. Let's do our traditional take-apart-the-script section. I'll place a nice TEMPLATE from the file spheretemp_loot.scp.

<tt><font color="darkblue">[TEMPLATE 101505]<br />
DEFNAME=backpack_poor<br />
CATEGORY=Item Templates<br />
SUBSECTION=Loot Templates<br />
DESCRIPTION=Poor Backpack<br />
CONTAINER=i_backpack<br />
ITEM={ random_food 1 0 3 },{ 1 3 }<br />
ITEM={ random_bottle 1 0 8 }<br />
ITEM={ random_light 1 0 8 }<br />
ITEM={ random_male_tops 1 0 4 }<br />
COLOR=colors_all<br />
ITEM={ random_male_pants 1 0 4 }<br />
COLOR=colors_all<br />
ITEM=POOR_GOLD_PILE<br /></font></tt>

Wow, that looks confusing. But don't worry, by the time we're done, you'll know exactly what it means!

<font color="darkblue">[TEMPLATE 101505]</font>: First of all, we look at the header for our template. An interesting thing about templates is that the item name cannot be a DEFNAME like all other scripts. It must be a ridiculously high number like 101505.
<font color="darkblue">DEFNAME=backpack_poor</font>: Of course, SPHERE developers are not entirely evil, and have provided us with the ability to give these scary numbers a DEFNAME for easier access. You tell me, which would you rather type? ".add 101505" or ".add backpack_poor"? I thought so.

'''Note:''' Since .56c, move DEFNAME to [TEMPLATE ...], e.g. [TEMPLATE backpack_poor]

<font color="darkblue">CATEGORY, SUBSECTION, DESCRIPTION</font>: Axis crap. Optional. See the previous sections for a description of what these do.

<font color="darkblue">CONTAINER=i_backpack</font>: Ahh, now we're getting down to the meat of this thing. This specifies the holding container that all other items in this template will be in. When you add the item in game, you will see this container. In this case, it's a backpack. Simple enough. This can be any valid item with a TYPE of t_container or t_container_locked.

<font color="darkblue">ITEM={ random_food 1 0 3},{1 3}</font> Well, that's certainly cryptic. I think we need to break this line down even further.

But first, we're going to cover RANDOM SELECTORS! Sounds like fun doesn't it? Nah, it doesn't sound fun to me either, but it's absolutely necessary to a good shard.

Basically, they are an easy way to get different numbers with one command. What fun would a shard be where you killed a dragon and got a Platemail of Magic Stuff and a Super Duper Sword of Power every single time? Everyone would be running around with them. What we need is some variety!

There are two types of random selectors: weighted random and ranged random. Weighted random makes a statement like this: "Ok, 1 out of 10 times pick Number A, 3 out of 10 times pick Number B, and 6 out of 10 times pick number C". Ranged random makes a statement like this: "Pick any number between the two numbers I give you".

Our example actually has an example of both ranged random and weighted random. We'll cover them in the order they appear:

{ random_food 1 0 3}

This is a weighted random selector. The way to interpret these is to take the numbers that appear between the parentheses and divide them into sets of two:

random_food 1<br>
0 3

Add up the second numbers in both sets, and we get 4. This tells SPHERE, "Ok, 1 out of four times, I want you to pick random_food, and 3 out of four times, I want you to pick zero." You can even have random sets within random sets, but then it just gets confusing.

{ { random_food 1 0 3} 1 random_clothing 1}

Can you figure it out?

random_clothing 1
{ random_food 1 0 3} 1

2 is our magic number in this case. One out of two times, SPHERE will pick random_clothing, and one out of two times, SPHERE will pick our previous random selector, which will then select one of its own options. If you're confused at this point, don't worry. This is extremely rare, and we'll see in a moment how templates help us to solve this problem.

I did mention, though, that there is another type of random selector, and you can probably see what it is:

{1 3}

NOTE: Spacing here is important. There must be ZERO spaces between the { and the first number, or the } and the last number. It will behave strangely otherwise.

This tells SPHERE "Pick a number between 1 and 3, inclusive". Inclusive means that SPHERE can pick 1, 3, or any number in between. In this case, the range is rather limited. SPHERE will give you a 1, 2 or 3 here. Ranged random selectors are actually more often used inside of weighted random selectors.

{ {1 3} 3 {4 9} 1}

"One out of four times, pick a number between 4 and 9. Three out of four times, pick a number between 1 and 3."

And with that out of the way, we're going to analyze the actual line of the script from above. The Piece What the Line does ITEM=
This tells the script "Ok, we're going to add an item to this container. Anything after the = tells the script exactly what it is we're adding and in what amounts. You could easily say ITEM=i_platemail_chest, or something like that, without the mysterious { } sections, but the reason templates are interesting is because they can vary greatly.

<font color="darkblue">{ random_food 1 0 3}</font>

This is the item you will be creating. As we can see from our weighted random selector lesson, 1 out of 4 times, it will be random_food, and 3 out of 4 times, it will be zero. If an ITEM is zero, nothing will be created this time. Basically this is saying "There will be a one in four chance of getting random_food in this container." What is random_food you ask? Well, it happens to be another TEMPLATE, defined in spheretemplate.scp, I believe.

{1 3} This is the amount of the item that will be created. You should recognize this as a ranged random selector. This tells SPHERE to put between 1 and 3 of this item into the container. Of course, if the item is zero as selected above, this has no effect since one nothing and three nothings are still nothing.

So basically, that is a template script. You then fill it with as many items as you want. You may also notice the following construction:

ITEM=i_sword_long,R11

This is a shorthand way of writing this:

ITEM={ i_sword_long 1 0 10 }

R11 means "one out of 11 chance of finding this item". And you can add an amount selector to the end of that as well, which makes it look long and scary:

ITEM=i_sword_long,R11,{4 5}

But why would you want 4 or 5 long swords in one item? That would be bizzare. :)

And that's about it for templates. Congratulations, you're finished with chapter 1. Now you should be able to understand the examples to follow on the next section. You may also have some questions which are addressed in the common questions area. If you have a question which is not addressed there, perhaps it is too advanced of a topic for chapter 1. I assure you almost every aspect of SPHERE scripting will be covered in later chapters.

''(A template example by Belgar)''

<tt><font color="darkblue">[TEMPLATE tm_necromancer]<br />
CONTAINER=i_bag<br />
ITEM=random_necro_scroll<br />
ITEM=random_necro_scroll<br />
ITEM=random_necro_reagent, {5 12}<br />
ITEM=random_reagent, {5 12}<br />
ITEM=random_necro_reagent, {5 12}<br /></font></tt>

==Examples==
Or, um. Well I guess there really isn't another way to say "Examples".

This shall be my attempt to create the most basic new items available. You will see things in these examples that are NOT mentioned in the tutorials. The major factor will be ON=@Create, which is the primary topic of Chapter 2. Just know for now that things you can change in game (color, etc) must go under ON=@Create.

'''Example 1''': A Red Sword

<tt><font color="darkblue">[ITEMDEF i_sword_red]<br />
ID=i_sword_viking<br />
TYPE=t_weapon_sword<br />
NAME=The Red Sword<br />
CATEGORY=Weapons<br />
SUBSECTION=New Swords<br />
DESCRIPTION=Red Sword<br />

ON=@Create
:COLOR=colors_red // This is a comment. Comments are ignored by SPHERE.<br /></font></tt>

Wait, what is this weird <font color="darkblue">//</font> thing we've got going here? That's called a comment. It's completely ignored by SPHERE, so you can write whatever you want to the end of the line after //. You cannot have multi-line comments in SPHERE unless you use a new //, so don't even try it. SPHERE will give funky errors and then you'll have fun finding them.

'''Example 2''': A blue ettin

<tt><font color="darkblue">[CHARDEF c_ettin_blue]<br />
ID=02 // You could just as easily use c_ettin here.<br />
NAME=My Blue Ettin<br />
<br />
<br />
ON=@Create<br />
:COLOR=02 // This is a dark blue color. It's often used for Counselor robes. Remember it.<br /></font></tt>

'''Example 3''': A template from the file, since I'm too lazy to write one myself

<tt><font color="darkblue">[TEMPLATE 101521]<br />
DEFNAME=goodie_meager_1<br />
CATEGORY=Item Templates<br />
SUBSECTION=Loot Templates<br />
DESCRIPTION=Meager Goodie 1<br />
ITEM={ meager_gold_pile 1 backpack_meager 1 pouch_meager 1 }<br />
ITEM={ random_boots 1 0 4 }<br />
ITEM={ random_gorget 1 0 4 }<br />
ITEM={ random_staff 1 0 4 }<br />
ITEM={ random_necklace 1 0 4 }<br />
ITEM={ i_cape 1 0 9 }<br />
<font color="darkred">COLOR=colors_all</font><br /></font></tt>

You may notice something new here (especially since I highlighted it in red), and yes, it is legal. Any lines between ITEM= lines will affect the previously created item. The COLOR= line here affects the ITEM created by the line

ITEM={ i_cape 1 0 9 }

Remember, the best way to learn this type of scripts is to read the scripts provided for you in files like sphereitem_colorarm.scp and sphereitem_beers.scp.

[[Category:Tutorials]]

Chapter 1

2022-08-19T19:21:01Z

Soulless:

{{Languages|Chapter_1}}

==Numbers==

The first thing you'll notice while looking through SPHERE scripts is the wide variety of ways to write numbers. Since numbers are insanely important to a SPHERE scripter, this is the first lesson in the series. By the end of the lesson, I hope that you have a general understanding of hexadecimal, decimal and binary numbering systems, and SPHERE's ways of identifying each. You will also know how to generate random numbers either from a series or from a list of choices.

The first thing you need to understand is that the way we count is not the only way to count. Our numbering system contains ten digits (0, 1, 2, 3, 4, 5, 6, 7, 8, and 9). Therefore, at the tenth number, we have to add an extra column to the number, and reset the first column to zero (1, 2, 3, 4, 5, 6, 7, 8, 9, 10). That's why our numbering system works the way it does.

In the decimal system, without realizing it, we write our numbers to mean powers of ten. For example, if you take the number 17282 (which I just made up), and divide it down we get this:

{| border="1"
| Power of ten || 4 || 3 || 2 || 1 || 0
|-
| Ten to that power || 10000 || 1000 || 100 || 10 || 1
|-
| Digit || 1 || 7 || 2 || 8 || 2
|}

To reach the number 17282 from here, we simply take ten to the power of the number in the top row, multiply it by the number in the bottom row, and then add all those numbers together. We get 10000 + 7000 + 200 + 80 + 2. Obviously, this is simplistic, and we do it without even realizing we're doing it. You're probably thinking "Riiight, what does Taran think he's getting at?" Well, we aren't so special that our counting system is the only way to count.

Now, there is another numbering system that is used almost solely by computers. It only contains two numbers (1 and 0) and is therefore called the binary (meaning two) system. Binary numbers look like this: 101011101101, and you often see them in ads for computers and other electronic equipment (oftentimes they are shown streaming out of a CD player on television commercials). Digits in the binary system are called bits (short for BInary digiT)Binary numbers are almost impossible to translate to decimal directly, and so some math must be done.

Binary works in the same way, by adding powers of a number. In the case of binary, since there are two numbers in the whole system, that number is naturally two. Here are some examples of powers of two. These numbers might look familiar to some people.

{| border="1"
| Power of 2 || Binary number || Decimal number
|-
| 0 || 1 || 1
|-
| 1 || 10 || 2
|-
| 2 || 100 || 4
|-
| 3 || 1000 || 8
|-
| 4 || 10000 || 16
|-
| 5 || 100000 || 32
|-
| 6 || 1000000 || 64
|-
| 7 || 10000000 || 128
|-
| 8 || 100000000 || 256
|-
| 9 || 1000000000 || 512
|-
| 10 || 10000000000 || 1024
|}

Ridiculous eh? :)

We need a better system! The reason we get such strange results is because 10 is not a power of two. We need to find a system where the number base IS a power of two. The most commonly used system used is base-16, or hexadecimal. I'm sure if you've perused the SPHERE boards, you've seen the word hex floating around. No, this isn't a curse or evil spell, it's a short way of saying "hexadecimal".

{| border="1"
| Binary || Decimal || Hexadecimal
|-
| 1 || 1 || 1
|-
| 10 || 2 || 2
|-
| 11 || 3 || 3
|-
| 100 || 4 || 4
|-
| 101 || 5 || 5
|-
| 110 || 6 || 6
|-
| 111 || 7 || 7
|-
| 1000 || 8 || 8
|-
| 1001 || 9 || 9
|-
| 1010 || 10 || A
|-
| 1011 || 11 || B
|-
| 1100 || 12 || C
|-
| 1101 || 13 || D
|-
| 1110 || 14 || E
|-
| 1111 || 15 || F
|-
| 10000 || 16 || 10
|}

See how it works? There are an extra six numbers added onto the end of the system, represented by the first six letters of the alphabet.

Now, in SPHERE scripting, you are almost NEVER going to be dealing with binary numbers that are NOT powers of two, and if you do, you can simply use any scientific calculator to figure it out. But it's a lot easier in hexadecimal.

(This is the last table, I promise!!)
{| border="1"
| Binary || Hexadecimal
|-
| 000000001 (1) || 01
|-
| 000000010 (2) || 02
|-
| 000000100 (3) || 04
|-
| 000001000 (4) || 08
|-
| 000010000 (5) || 010
|-
| 000100000 (6) || 020
|-
| 001000000 (7) || 040
|-
| 010000000 (8) || 080
|-
| 100000000 (9) || 0100
|}

As you can see, there's a bit of a pattern in the hexadecimal column. You might be thinking, there seems to be some sort of pattern of the numbers 1, 2, 4 and 8. And you would be right. Another detail you may notice is the zeros in front of the hexadecimal numbers (like 0100, rather than just 100). In SPHERE, that 0 tells the script "Hey, this number is HEX!" 0100 and 100 are very different numbers.

Let's say, for a SPHERE script, you need to set the 13th bit of a number (FLAGS, for example), you could write something like this:

'''SRC.FLAGS |= 8192'''

But would you really remember that 8192 is 2 to the 13th power? I didn't think so. What would be easier is to go down through your list in your head, until you reach the 13th number. (Remember, START AT ZERO when you're counting!)

{| border="1"
| 01 || 02 || 04 || 08 || 010 || 020 || 040 || 080 || 0100 || 0200 || 0400 || 0800 || 01000 || 02000
|-
| 2^0 || 2^1 || 2^2 || 2^3 || 2^4 || 2^5 || 2^6 || 2^7 || 2^8 || 2^9 || 2^10 || 2^11 || 2^12 || 2^13
|}

And there you have it. The first 14 powers of two in hexademical.

'''SRC.FLAGS |= 02000'''

The above code is identical to the previous example. 8192 (decimal) is EQUAL to 02000 (hexadecimal)

'''8192 = 02000'''

You may be saying, "How do I know he's just not making all of this up?" Well, our wonderful friends at Microsoft have provided us with a nice tool that converters from decimal to hexadecimal to binary to octal (ANOTHER numbering system that is useless in SPHERE, so we will not deal with it). It's called the Calculator. You may find it by clicking your start button, going to Programs, then Accessories. Calculator should be sitting there looking pretty. Once in the calculator program, go to the View menu, and click Scientific. You'll see the display drastically change. To convert a number between numbering systems, simply click on the original system (Dec), type a number (8192), then click on the button for the other system (Hex). Automagically, Windows will convert your decimal number to hexadecimal. Stick a zero on the front, and SPHERE will be perfectly happy with it.

This is probably the hardest thing in all of SPHERE scripting to understand. Luckily, because of the next section, you won't have to deal with scary numbers most of the time. If I still have you at the end of this lesson, I know you're going to do great!

Onward to some SPHERE scripting!

==Defnames==

Here's a list of scary numbers you might encounter while programming in SPHERE.

{| border="1"
| The Scary Number || What it means
|-
| 0eed || ID of a gold coin
|-
| 0dda || ID of a red moongate
|-
| 1650,1440 || Coordinates of Britain
|-
| 021 || The code number for red
|-
| 04000 || The invisible color
|-
| 04000efad || An item's serial number
|-
| 4 || The PLEVEL of a GM
|-
| 2048 (or 0800) || Flag for incognito spell
|-
| 010 (or 16) || Memory type for aggressors
|}

Obviously, no one is going to want to remember those numbers. Back in the old days, before SPHERE and TUS (pre-.50 SPHERE) and even into the mists of Grayworld (pre-.41 TUS), we all had to remember those numbers. I know all of those numbers I just said (except the serial number which I just made up), plus a couple dozen more, by heart. Luckily for those of you who don't like to sit around remembering numbers all day, SPHERE has developed a system whereby things can be identified by names instead of numbers.

Actually, the things are still identified by numbers. It's the numbers which are identified by the name.

In the game, type .add 0eed and press enter. A target will come up and you'll create a single gold piece.

Now type .add i_gold and press enter. You will create the same single gold piece.

Now which is easier to remember, 0eed or i_gold. I would say that i_gold wins by a long shot. But how does this magic happen? Let's take a look at the script definition for a piece of gold. Don't worry about understanding it. I'll explain item scripts in full in the next section! You can find this script in the file sphere_item_resources.scp.

<tt><font color="darkgreen">[ITEMDEF 0eed]<br />
//gold coin<br />
<font color="ff0000">DEFNAME=i_gold</font><br />
TYPE=T_GOLD<br />
VALUE=1<br />
CATEGORY=Provisions - Miscellaneous<br />
SUBSECTION=Coins<br />
DESCRIPTION=Gold Coin<br />
DUPELIST=0eee,0eef</font><br /></tt>

I have highlighted in red the line that really matters for the purposes of this lesson. Take note of the 0eed in the top line of the script, and then ignore the rest of it. That 0eed is the real item number of this item. We'll cover item numbers more in the next section.

But the real line we want to see the <font color="ff0000">DEFNAME=i_gold</font> line. This is where the script tells the server, "I want item 0eed to be identified by the text i_gold from here on." If you tried to refer to i_gold before the server read this script (more on reordering scripts in [[Chapter 2]], the server would spit out an error, but now it knows what that refers to, so you can use it in the game or in another script.

You should ALWAYS give items you create a DEFNAME that fits the item. Usually the defname will be defined in the [ITEMDEF] identifier itself (again, more on this later), but if you insist upon using numbers, be sure you give it an easy-to-remember name (not golden_gulash for a viking sword). It makes it easier to remember names than numbers.

A second way to define a DEFNAME is by using the [DEFNAME] tag in a script. Here is an example of that:

<tt><font color="darkgreen">[DEFNAME colors]<br />
color_blue 02<br />
color_red 021<br />
color_green 041</font><br /></tt>

You'll find a script similar to this in spheredefs.scp, another file that should be loaded before any other file.

Here's the rundown on this script, line by line:

'''Line 1''': This is where the type of script and the defname (yes colors is the defname of this script) is defined. This tells the server what type of script to expect between this and the next identifier (identifiers are the lines contained in square brackets). All identifiers have this format. The first parameter is the script type. These are numerous, and I will go over them as we get to them. The second parameter is either an ID number or a defname. In most cases, in the scripts you write, it will be a defname. The only exceptions to this I can think of would be if you used a program to insert a new item into the client files.

'''Lines 2-4''': These set up your individual DEFNAME pieces. It says that color_blue is equal to 02, color_red is equal to 021, and color_green is equal to 041. You may have any number of spaces between the name and the value. The definitions contained in spheredefs.scp are among the most useful you will encounter, as they prevent you from writing the long scary numbers we went over in the previous section. These include things like names for flags, names for item attributes, names for the built-in MIDI or MP3 music, names for memory types, and many other things. Look through the file to see what it offers you.

That's about it for DEFNAMEs. You'll see more of these later as we cover other types of scripts.

Now go on to learn about items.

==ITEMDEF==
Or, how to make a mountain from a molehill, SPHERE style

Most people make item scripting much harder than it needs to be. For the purposes of this tutorial, since there is a more advanced one later, we will simply go over the basics of an ITEM script, line by line. We'll be using the gold script from the previous lesson, provided I can find it again....

Ah, here it is, conveniently color coded for your viewing pleasure!

<spherescript>[ITEMDEF 0eed]
//gold coin
DEFNAME=i_gold
TYPE=T_GOLD
VALUE=1
CATEGORY=Provisions - Miscellaneous
SUBSECTION=Coins
DESCRIPTION=Gold Coin
DUPELIST=0eee,0eef</spherescript>

This is the simplest of item scripts, since it has no additional behaviors beyond existing. I will go through this line by line, describing to you what each line does, and how it affects the end result.

'''Line 1''': [ITEMDEF 0eed]

The first lines of an item script are frequently the most important. Basically, this line tells the server "Hey this is an item and I want it to be called 0eed!" The server then looks through one of the client files (specifically art.idx), and identifies whether or not this item is one of the built-in items. I think all items below 04500 are defined as built-in items, so never define a new item in that range. By typing this line, you tell the server that an item script is following. You also define 0eed as a valid item, which will definitely help later on when you try to give gold to players!

'''Line 2''': // gold coin

This is the SPHERE version of comment. C programmers will recognize the format immediately. If you type // on any line of code, everything beyond that is ignored by the script reader. This can be on a line by itself, or at the end of a line to explain what the specific line does. In all cases, it won't affect your program, just make it easier to read.

'''Line 3''': DEFNAME=i_gold

You should know by now what this does! If you don't, go back and read the previous lesson! It tells the server that i_gold and 0eed mean the same thing. In item scripts, all parameters are defined in that format:

variable=value

You will see later on, when we get into scripting, how that format will help you more than you would believe. Items have a good number of variables that you can define, including:

* DEFNAME
* ID
* TYPE
* VALUE
* RESOURCES
Other variables depend on the value of the TYPE. Which leads us right into...

'''Line 4''': TYPE=t_gold

The first thing you might say is "What the heck is t_gold?" Well it's a DEFNAME. Actually it's a number. And that number is 72. If you want to check me on this, look in spheredefs.scp, it's there! Writing TYPE=72 would have the exact same effect.

There are, currently, 183 built-in item types. These are hardcoded item types that contain predefined actions for an item. If an item has no type, when you click it, you get the "You cannot think of a way to use that item" message. There is a complete list of types, and how to set them up, here . All you need to know for now is that setting the type of this item to t_gold has no effect other than to make the item act like a gold coin (i.e. you can buy stuff with it!) Setting another item to type t_gold would probably make the server think that you can buy stuff with that item too. I've never tried this. It might be an interesting way to have unique currencies...

'''Line 5''': VALUE=1

This defines how much the item costs when purchased, in gold. Of course, this is one gold piece, which is worth, well, one gold piece. So the value of the item is one.

'''Lines 6-8''': CATEGORY, SUBSECTION, DESCRIPTION

These are lines used only by SPHERE's GM tool, Axis, which actually saves you a lot of work by typing ".add i_gold" for you. More importantly, it types ".add 01737" and things like that for you, for items that were not important enough to get their own separate DEFNAME.

'''Line 9''': DUPEITEM

It would be a ton of work for the SPHERE team to define all 8000 items that came with the game, especially when many of them are the same. (For an example of this, use the .xflip command on a door or sign. It cycles through all of the DUPEITEMs for that the item being flipped.) The numbers listed here are item numbers, which probably have not been defined yet. Here is the script for item 0eee:

<spherescript>[ITEMDEF 0eee]
//gold coins
DUPEITEM=0eed
CATEGORY=Provisions - Miscellaneous
SUBSECTION=Coins
DESCRIPTION=Gold Coins</spherescript>

As you can see, there is only one parameter for this whole item. It reiterates the DUPEITEM and sends the server looking to our 0eed (or i_gold) item for more information, such as TYPE and VALUE. DUPEITEM only exists to save typing. You probably won't use it.

==CHARDEF==
Or, what it takes to make a naked man who can stand around and say "Huh?"

NPCs... They make the world go around. They are what makes UO a unique multiplayer game. The monsters and NPCs you create make your server unique from any other. This section of chapter one will cover how to create a simple naked man who walks around and says little more than "Huh?" (or "Stop thief!" if you tell him to!).

First of all, we'll look at the script for a simple naked man. I'm pulling this out of spherechar_human.scp.

<spherescript>[CHARDEF 0190]
DEFNAME=c_man
Name=Man
ICON=i_pet_MAN
CAN=MT_EQUIP|MT_WALK|MT_RUN|MT_USEHANDS
RESOURCES=i_flesh_head, i_flesh_torso, i_flesh_right_arm, i_flesh_left_arm
FOODTYPE=15 t_food, t_fruit
DESIRES=i_gold,e_notoriety
AVERSIONS=t_TRAP,t_eerie_stuff
SHELTER=r_house
BLOODCOLOR=0

TSPEECH=spk_human_prime
TSPEECH=spk_human_default
TEVENTS=e_Human_HearUnk
DESCRIPTION=Man
SUBSECTION=Miscellaneous
CATEGORY=Civilized</spherescript>

As you can see, it doesn't look a lot different than the item scripts we examined in the previous section. There are a lot of variables set that are the same, including DEFNAME, DESCRIPTION, and the other Axis variables.

But, there are a lot of new things here that we will again go over, one line at a time! And it's longer this time! Let the good times roll! (Sorry if you're not American.. All my American clichés are probably growing irritating!)

'''Line 1''': [CHARDEF 0190]

Surprise surprise! It's an identifier, telling the server that we are going to be defined a character between this and the next [identifier]. And we also tell it that our character, or NPC, will have the ID 0190. The server knows that this ID is one of the built-in IDs. In fact, it's the ID of a naked man. You also know that 0190 is hexadecimal is 400 in decimal right? :) Well why didn't you know that! Oh I'm just kidding, you don't need to know things like that.

'''Line 2''': DEFNAME=c_man

Nothing new here. c_man is now the same as 0190. Most character DEFNAMEs will begin with C and then an underscore (c_) like you see above.

'''Line 3''': Name=Man

Oh oh! Something new! Items come with default names, built in to the server. Characters don't. So we have to assign him a name. We can give him any name we want, but since this isn't a specific man, we just give him a name telling us what he is. In this case "Man".

'''Line 4''': ICON=i_pet_man

It took me a while to figure this one out. ICON defines what little picture you see when you're using the Tracking skill and all those little miniature creatures appear in the window. Those are actually items, all the i_pet items. To find out what the i_pet item for your creature should be, create him in the game using .addnpc, then use the .shrink command on him. The ID of the item that he becomes is your i_pet item.

'''Line 5''': CAN=mt_*

(In case you don't know, * means "anything" for those who use Linux.)

This is one of the most important lines of your character script, next to the ID we give him in the first line. First, because it allows us to tell the game what our NPC can do and what he can't do. There are only a few mt_* items, all of which are defined in spheredefs.scp. For the purpose of the lesson, I am going to copy them here. (The purple comments are mine.)

<spherescript>MT_NONMOVER 0 // We can't move at all
MT_GHOST 01 // We can walk through doors and such, like a ghost
MT_SWIM 02 // I can swim! (Water elementals, dolphins, etc)
MT_WALK 04 // I can move. Set this if you want your creature to move.
MT_FLY 010 // Moves through (supposed to be over) trees
MT_FIRE_IMMUNE 020 // Immune to damage by fire. Setting this on a player is bad. :)
MT_EQUIP 00100 // Can equip things
MT_USEHANDS 00200 // Can use his hands to carry things (or open doors)
MT_MALE 0 // Is a male
MT_FEMALE 00800 // Is a female
MT_NONHUM 01000 // Non-human. I'm not sure what this does.
MT_RUN 02000 // Can move really fast!</spherescript>

According to this chart, we can see that if we don't give a creature a CAN flag, it will be an MT_MALE and an MT_NONMOVER (the two zeros). You can see from the example that by putting a | (found by pressing shift+backslash) between two CAN flags, we can give him more than one. In this case, we allow our man to equip things, walk, run, and use his hands. (An interesting fact is, even creatures that don't have hands can be set to use their hands, thus allowing them to carry light sources. Fire elementals do this. That's how they glow.)

'''Line 6''': RESOURCES

Resources is a very morbid name for this setting. Especially for a person. These are the items that you get whenever you chop up this creature's corpse. Scary eh? :)

'''Line 7-10''': FOODTYPE, DESIRES, AVERSIONS

'''FOODTYPE''': Defines what kind of food the npc will eat and if NPC_AI_FOOD is on it'll make the npc look for this food + grass when he's hunger.

'''DESIRES''': Defines what kind of items will the npc be interested in, if NPC_AI_EXTRA is on it'll show what items the npc will loot of players corpses or walk towards when it's on the ground.

'''AVERSIONS''': No idea, but I think it tells the npc what sort of NPCs he'll try to fight, for example: I have a horse with e_horse as an event, and an imp without any events, if the npc has AVERSIONS=e_horse it'll prefer to fight the horse.

'''Line 11''': BLOODCOLOR

Ever wanted to make your players have green blood? This is where you do it! A color number or a color defname will work fine. (Try to learn the numbers for common colors, it makes it so much easier.)

The rest of it: TSPEECH and TEVENTS

We're going to cover these in sections of their own. They are probably the most complex topics in scripting! (How many times do you suppose I'm going to say that before it's actually true?)

''<font color="darkblue">Some other things:</font>''

On 56B we have some other fields like MOVERATE,RESLEVEL,RESDISPDNID and RESDISPDNHUE. They sound some difficult and strange thing but they aren't. Here's the explanation for them:

'''MOVERATE''': This setting (that can only be writed at the npc chardef) controls how fast the npc moves. The smaller the value, the faster the npc is. For example, if I have a horse chardef with default moverate (100) and another with moverate=60, the one with 60 will walk and run a lot faster than the other horse. This is great for making really difficult monsters to kill.

'''TAG.OVERRIDE.MOVEDELAY''' :Overrides completely the moverate checks and setting the next movement to the given timer, eg 'tag.override.moverate=250' makes the npc move each 250 milliseconds when walking.

'''RESLEVEL''': This tells sphere what version of uo this monster is from, for example, a Wanderer of the Void will have RESLEVEL=3 (3=AOS) (see sphere_defs.scp for a complete list), so only accounts with RESDISP 3 or bigger can see this monster as he really is.

''NOTE'': If you set a lower value for RESLEVEL, if the player doesn't have this npc anim he'll crash.

'''RESDISPDNID''': As you probably have seen, I used a lot of "as he really" is, exactly because of this setting, this tells the client what monster will the player see instead of the correct one. For example, this Wanderer of the Void will show as Wanderer of the Void for those who has ACCOUNT.RESDISP=3 or bigger, but for those who has smaller values it'll show as a c_spectre (if you so define).

'''RESDISPDNHUE''': This defines what color will the player see the monster if the RESDISPDNID id is shown to him (have an account.resdisp lower than the reslevel of this char)

Here's an example for those new settings:

<spherescript>[CHARDEF 310]
DEFNAME=c_Wailing_Banshee
NAME=Wailing Banshee
SOUND=snd_monster_zombie1
ICON=i_pet_wailingbanshee
DAM=11,16
RESDISPDNID=c_spectre
RESLEVEL=3
RESDISPDNHUE=01
ARMOR=20
CAN=MT_WALK|MT_FLY
DESIRES=i_gold,e_notoriety,e_horses,c_man,c_woman,t_corpse
CATEGORY=New Monsters
SUBSECTION=AOS
DESCRIPTION=Wailing Banshee

ON=@Create
NPC = brain_monster
FAME = {100 3000}
KARMA = {-5000 -6999}
STR = {126 166}
INT = {86 115}
DEX = {41 75}
MAGICRESISTANCE = {75.0 95.0}
TACTICS = {45.0 75.0}
WRESTLING = {50.0 70.0}

ON=@NpcRestock
ITEM = i_gold, {50 100}
ITEM = i_reag_daemon_bone, {2 6}</spherescript>

And there you have it. A simple character script and some new things. Read the chapter that is all about making NPCs later in the tutorial.

==TEMPLATE==
Or, how to put great laggy quantities of items into one unlaggy container.

You've all seen it. Those shards out there that don't use TEMPLATEs. When you kill, say, a dragon, on those shards, and go to loot him, you find that rather than neatly organized containers, there are 100 potions scattered about the loot window. Not only that, but all your magical weapons are buried neatly beneath them!

How do we solve this problem? Well, SPHERE has given us the handy tool of TEMPLATEs. These allow you to define a container item, AND the items inside of it, AT THE SAME TIME. Isn't that neat? I thought so too, when I first figured out what they were. Let's do our traditional take-apart-the-script section. I'll place a nice TEMPLATE from the file spheretemp_loot.scp.

<tt><font color="darkblue">[TEMPLATE 101505]<br />
DEFNAME=backpack_poor<br />
CATEGORY=Item Templates<br />
SUBSECTION=Loot Templates<br />
DESCRIPTION=Poor Backpack<br />
CONTAINER=i_backpack<br />
ITEM={ random_food 1 0 3 },{ 1 3 }<br />
ITEM={ random_bottle 1 0 8 }<br />
ITEM={ random_light 1 0 8 }<br />
ITEM={ random_male_tops 1 0 4 }<br />
COLOR=colors_all<br />
ITEM={ random_male_pants 1 0 4 }<br />
COLOR=colors_all<br />
ITEM=POOR_GOLD_PILE<br /></font></tt>

Wow, that looks confusing. But don't worry, by the time we're done, you'll know exactly what it means!

<font color="darkblue">[TEMPLATE 101505]</font>: First of all, we look at the header for our template. An interesting thing about templates is that the item name cannot be a DEFNAME like all other scripts. It must be a ridiculously high number like 101505.
<font color="darkblue">DEFNAME=backpack_poor</font>: Of course, SPHERE developers are not entirely evil, and have provided us with the ability to give these scary numbers a DEFNAME for easier access. You tell me, which would you rather type? ".add 101505" or ".add backpack_poor"? I thought so.

'''Note:''' Since .56c, move DEFNAME to [TEMPLATE ...], e.g. [TEMPLATE backpack_poor]

<font color="darkblue">CATEGORY, SUBSECTION, DESCRIPTION</font>: Axis crap. Optional. See the previous sections for a description of what these do.

<font color="darkblue">CONTAINER=i_backpack</font>: Ahh, now we're getting down to the meat of this thing. This specifies the holding container that all other items in this template will be in. When you add the item in game, you will see this container. In this case, it's a backpack. Simple enough. This can be any valid item with a TYPE of t_container or t_container_locked.

<font color="darkblue">ITEM={ random_food 1 0 3},{1 3}</font> Well, that's certainly cryptic. I think we need to break this line down even further.

But first, we're going to cover RANDOM SELECTORS! Sounds like fun doesn't it? Nah, it doesn't sound fun to me either, but it's absolutely necessary to a good shard.

Basically, they are an easy way to get different numbers with one command. What fun would a shard be where you killed a dragon and got a Platemail of Magic Stuff and a Super Duper Sword of Power every single time? Everyone would be running around with them. What we need is some variety!

There are two types of random selectors: weighted random and ranged random. Weighted random makes a statement like this: "Ok, 1 out of 10 times pick Number A, 3 out of 10 times pick Number B, and 6 out of 10 times pick number C". Ranged random makes a statement like this: "Pick any number between the two numbers I give you".

Our example actually has an example of both ranged random and weighted random. We'll cover them in the order they appear:

{ random_food 1 0 3}

This is a weighted random selector. The way to interpret these is to take the numbers that appear between the parentheses and divide them into sets of two:

random_food 1<br>
0 3

Add up the second numbers in both sets, and we get 4. This tells SPHERE, "Ok, 1 out of four times, I want you to pick random_food, and 3 out of four times, I want you to pick zero." You can even have random sets within random sets, but then it just gets confusing.

{ { random_food 1 0 3} 1 random_clothing 1}

Can you figure it out?

random_clothing 1
{ random_food 1 0 3} 1

2 is our magic number in this case. One out of two times, SPHERE will pick random_clothing, and one out of two times, SPHERE will pick our previous random selector, which will then select one of its own options. If you're confused at this point, don't worry. This is extremely rare, and we'll see in a moment how templates help us to solve this problem.

I did mention, though, that there is another type of random selector, and you can probably see what it is:

{1 3}

NOTE: Spacing here is important. There must be ZERO spaces between the { and the first number, or the } and the last number. It will behave strangely otherwise.

This tells SPHERE "Pick a number between 1 and 3, inclusive". Inclusive means that SPHERE can pick 1, 3, or any number in between. In this case, the range is rather limited. SPHERE will give you a 1, 2 or 3 here. Ranged random selectors are actually more often used inside of weighted random selectors.

{ {1 3} 3 {4 9} 1}

"One out of four times, pick a number between 4 and 9. Three out of four times, pick a number between 1 and 3."

And with that out of the way, we're going to analyze the actual line of the script from above. The Piece What the Line does ITEM=
This tells the script "Ok, we're going to add an item to this container. Anything after the = tells the script exactly what it is we're adding and in what amounts. You could easily say ITEM=i_platemail_chest, or something like that, without the mysterious { } sections, but the reason templates are interesting is because they can vary greatly.

<font color="darkblue">{ random_food 1 0 3}</font>

This is the item you will be creating. As we can see from our weighted random selector lesson, 1 out of 4 times, it will be random_food, and 3 out of 4 times, it will be zero. If an ITEM is zero, nothing will be created this time. Basically this is saying "There will be a one in four chance of getting random_food in this container." What is random_food you ask? Well, it happens to be another TEMPLATE, defined in spheretemplate.scp, I believe.

{1 3} This is the amount of the item that will be created. You should recognize this as a ranged random selector. This tells SPHERE to put between 1 and 3 of this item into the container. Of course, if the item is zero as selected above, this has no effect since one nothing and three nothings are still nothing.

So basically, that is a template script. You then fill it with as many items as you want. You may also notice the following construction:

ITEM=i_sword_long,R11

This is a shorthand way of writing this:

ITEM={ i_sword_long 1 0 10 }

R11 means "one out of 11 chance of finding this item". And you can add an amount selector to the end of that as well, which makes it look long and scary:

ITEM=i_sword_long,R11,{4 5}

But why would you want 4 or 5 long swords in one item? That would be bizzare. :)

And that's about it for templates. Congratulations, you're finished with chapter 1. Now you should be able to understand the examples to follow on the next section. You may also have some questions which are addressed in the common questions area. If you have a question which is not addressed there, perhaps it is too advanced of a topic for chapter 1. I assure you almost every aspect of SPHERE scripting will be covered in later chapters.

''(A template example by Belgar)''

<tt><font color="darkblue">[TEMPLATE tm_necromancer]<br />
CONTAINER=i_bag<br />
ITEM=random_necro_scroll<br />
ITEM=random_necro_scroll<br />
ITEM=random_necro_reagent, {5 12}<br />
ITEM=random_reagent, {5 12}<br />
ITEM=random_necro_reagent, {5 12}<br /></font></tt>

==Examples==
Or, um. Well I guess there really isn't another way to say "Examples".

This shall be my attempt to create the most basic new items available. You will see things in these examples that are NOT mentioned in the tutorials. The major factor will be ON=@Create, which is the primary topic of Chapter 2. Just know for now that things you can change in game (color, etc) must go under ON=@Create.

'''Example 1''': A Red Sword

<tt><font color="darkblue">[ITEMDEF i_sword_red]<br />
ID=i_sword_viking<br />
TYPE=t_weapon_sword<br />
NAME=The Red Sword<br />
CATEGORY=Weapons<br />
SUBSECTION=New Swords<br />
DESCRIPTION=Red Sword<br />

ON=@Create
:COLOR=colors_red // This is a comment. Comments are ignored by SPHERE.<br /></font></tt>

Wait, what is this weird <font color="darkblue">//</font> thing we've got going here? That's called a comment. It's completely ignored by SPHERE, so you can write whatever you want to the end of the line after //. You cannot have multi-line comments in SPHERE unless you use a new //, so don't even try it. SPHERE will give funky errors and then you'll have fun finding them.

'''Example 2''': A blue ettin

<tt><font color="darkblue">[CHARDEF c_ettin_blue]<br />
ID=02 // You could just as easily use c_ettin here.<br />
NAME=My Blue Ettin<br />
<br />
<br />
ON=@Create<br />
:COLOR=02 // This is a dark blue color. It's often used for Counselor robes. Remember it.<br /></font></tt>

'''Example 3''': A template from the file, since I'm too lazy to write one myself

<tt><font color="darkblue">[TEMPLATE 101521]<br />
DEFNAME=goodie_meager_1<br />
CATEGORY=Item Templates<br />
SUBSECTION=Loot Templates<br />
DESCRIPTION=Meager Goodie 1<br />
ITEM={ meager_gold_pile 1 backpack_meager 1 pouch_meager 1 }<br />
ITEM={ random_boots 1 0 4 }<br />
ITEM={ random_gorget 1 0 4 }<br />
ITEM={ random_staff 1 0 4 }<br />
ITEM={ random_necklace 1 0 4 }<br />
ITEM={ i_cape 1 0 9 }<br />
<font color="darkred">COLOR=colors_all</font><br /></font></tt>

You may notice something new here (especially since I highlighted it in red), and yes, it is legal. Any lines between ITEM= lines will affect the previously created item. The COLOR= line here affects the ITEM created by the line

ITEM={ i_cape 1 0 9 }

Remember, the best way to learn this type of scripts is to read the scripts provided for you in files like sphereitem_colorarm.scp and sphereitem_beers.scp.

[[Category:Tutorials]]

Override TAGs

2022-08-19T19:20:13Z

Soulless: /* Character-based Override TAGs */

{{Languages|Override_TAGs}}

==Override Common Data==
Ever wondered why you can't change for example 'TDATA' values on a per-item basis? Or some default values from Sphere.ini?

The reason is simple: The majority of items, characters and situation will not need individual values there and are working fine with the default ones (either hardcoded or set in the INI or the *DEF sections), so it simply would be a waste of memory to store them again on each game object. Therefore for example a single crossbow in the world reads what items it needs as ammunition not from it's "WORLDITEM" data object, but from it's ITEMDEF (the TDATA property).

Alas, as time goes by for some stuff it showed reasonable to allow overriding the default values for a single item, character or even region. Nevertheless it still would be a waste of resources to give all crossbows an "ammunition" property what on almost all of them will read: "default". So the Sphere developers decided to store the respective individual changes in TAGs: If the TAG exists it will be used, if not, the default is used.

Common to most overrides is the syntax of the TAG's name: '''TAG.OVERRIDE.*''' - where "'''*'''" denotes the name of the respective tag. But there are also some others what were named before this naming scheme was established.

==Item-based Override TAGs==

{| border="1"
| '''TAG.ALWAYSSEND'''
| When optional flag OF_OsiMultiSight is on, all items inside a multi are not sent until entering the multi. If you want an item to be always sent, set TAG.ALWYASSEND to 1. This tag also can also go under the ITEMDEF section of an item.
|-
| '''TAG.NOSAVE'''
| If set to 1 the object will NOT be saved.
|-
| '''TAG.OVERRIDE.DAMAGETYPE'''
| Sets the damage type for a weapon (ARGN2 in @GetHit trigger).
|-
| '''TAG.OVERRIDE.DROPSOUND'''
| Overrides the sound that will be played when the item is dropped somewhere.
|-
| '''TAG.OVERRIDE_LIGHTID'''
| Overrides TDATA3 for lights (T_LIGHT_LIT, T_LIGHT_OUT). Take notice that there is an underscore in this TAG's name.
|-
| '''TAG.OVERRIDE.MAXITEMS'''
| Overrides the maximum number of items that can be placed into a container (default: 255)
|-
| '''TAG.OVERRIDE.MAXWEIGHT'''
| Overrides the maximum total weight that can be placed into a container.
|-
| '''TAG.OVERRIDE.PRACTICEMAX.SKILL_$skillid'''
| Overrides SKILLPRACTICEMAX setting from Sphere.ini for a particular skill. $skillid is the numeric ID of the skill.
|-
| '''TAG.OVERRIDE.SKILL'''
| Overrides the SKILL property of the ITEMDEF for a weapon.
|-
| '''TAG.OVERRIDE.SPEED'''
| Overrides the SPEED for a weapon.
|-
| '''TAG.OVERRIDE.SOUND_HIT'''
| Overrides the hit sound for a weapon. Take notice that there is an underscore in this TAG's name. (Removed in newer versions and is just AMMOSOUNDHIT=<Val> without the use of Tag.Override.<String>=<Val>)
|-
| '''TAG.OVERRIDE.SOUND_MISS'''
| Overrides the miss sound for a weapon. Take notice that there is an underscore in this TAG's name. (Removed in newer versions and is just AMMOSOUNDMISS=<Val> without the use of Tag.Override.<String>=<Val>)
|}

==Character-based Override TAGs==

{| border="1"
| '''TAG.DEATHFLAGS'''
| Changes some death related behaviour. The list of supported flags are in sphere_defs.scp.
|-
| '''TAG.MAXPLAYERPETS'''
| Overrides the maximum number of pets that a player can stable. Default is 10.
|-
| '''TAG.NAME.ALT'''
| Sets an alternative name, useful for incognito effects.
|-
| '''TAG.NAME.HUE'''
| Changes the colour of the name displayed above a character.
|-
| '''TAG.NAME.PREFIX'''
| Sets some text to display before the character's name.
|-
| '''TAG.NAME.SUFFIX'''
| Sets some text to display after the character's name.
|-
| '''TAG.NOSKILLMSG'''
| When set to 1, character will receive the "gainradius_not_met" defmessage (sphere_msgs.scp) when skillgain is aborted due to the GAINRADIUS on a skill.
|-

| '''TAG.OVERRIDE.MOVERATE'''
| Overrides the MOVERATE property of the CHARDEF.
|-
| '''TAG.OVERRIDE.MOVEDELAY'''
| Overrides completely the moverate checks and setting the next movement to the given timer, eg 'tag.override.moverate=250' makes the npc move each 250 milliseconds when walking.
|-
| '''TAG.OVERRIDE.RUNNINGPENALTY'''
| Overrides RUNNINGPENALTY from Sphere.ini
|-
| '''TAG.OVERRIDE.SKILLCAP_$skillid'''
| Overrides skill settings from the character's SKILLCLASS. $skillid is the numeric ID of the skill.
|-
| '''TAG.OVERRIDE.SKILLSUM'''
| Overrides SKILLSUM setting from the character's SKILLCLASS.
|-
| '''TAG.OVERRIDE.SPIDERWEB
| When set to 1, NPC will be able to drop spider webs (for a giant spider, if this set to 1 then it will stop it from dropping webs)
|-
| '''TAG.OVERRIDE.STAMINALOSSATWEIGHT'''
| Overrides STAMINALOSSATWEIGHT from Sphere.ini
|-
| '''TAG.OVERRIDE.STATCAP_$statid'''
| Overrides STR/DEX/INT settings from the character's SKILLCLASS. (0=STR, 1=INT, 2=DEX)
|-
| '''TAG.OVERRIDE.STATSUM
| Overrides STATSUM setting from the character's SKILLCLASS.
|-
| '''TAG.OVERRIDE.TRAINSKILLMAX'''
| Overrides NPCTRAINMAX setting from Sphere.ini
|-
| '''TAG.OVERRIDE.TRAINSKILLMAXPERCENT'''
| Overrides NPCTRAINPERCENT setting from Sphere.ini
|-
| '''TAG.PARTY_AUTODECLINEINVITE'''
| When set to 1, character will automatically decline party invitations.
|-
| '''TAG.PARTY_CANLOOTME'''
| When set to 1, party members will be allow to loot this character without it being counted as a criminal action (linked to the option in the party menu).
|-
| '''TAG.VENDORMARKUP'''
| This value is added to the markup percentage that vendors apply to their buy and sell prices. Since the default markup is 15%, this means that a vendor will sell something worth 100gp at 115gp and buy it back for 85gp. If you set this tag to -15 the markup will be cancelled out to 0%, or you can raise/lower it if you want your vendor to sell things at a higher/lower price.
|}

==Region-based Override TAGs==

{| border="1"
| '''TAG.ANNOUNCEMENT'''
| Sets a message to be announced to all who enters the region if REGION_FLAG_ANNOUNCE is set.
|-
| '''TAG.GUARDOWNER'''
| Specifies the owner of the region's guards (ex: "The City")
|-
| '''TAG.OVERRIDE.GUARDS'''
| Specifies the character that will be summoned when guards are called in the region, overriding the <tt>guards {c_h_guard 1 c_h_guard_f 1}</tt> defname in sphere_defs.scp
|-
| '''TAG.RED'''
| Sets the region as a safe place for evil. Murders are considered normal here.
If region is guarded, guards will be red and protect evil players.
|-
| '''TAG.VENDORMARKUP'''
| This value is added to the markup percentage that vendors apply to their buy and sell prices. Since the default markup is 15%, this means that a vendor will sell something worth 100gp at 115gp and buy it back for 85gp. If you set this tag to -15 the markup will be cancelled out to 0%, or you can raise/lower it if you want your vendor to sell things at a higher/lower price. If the vendor has this tag set directly on them then this region TAG will not be used.
|}

==Removed Override TAGs==
{| border="1"
| '''OLD TAG'''
| '''NEW Variable'''
| '''Description'''
|-
| '''TAG.BREATH.DAM
| Breath.Dam
| Overrides Damage done from fire breathing.
|-
| '''TAG.RANGE
| Range
| Range is now writable for both characters and items.
|-
| '''TAG.OVERRIDE.SHIPSPEED.PERIOD
| ShipSpeed.Period
| Overrides SHIPSPEED.PERIOD for a ship (the length of time it takes for the ship to move one step, in tenths of a second).
|-
| '''TAG.OVERRIDE.SHIPSPEED.TILES
| ShipSpeed.Tiles
| Overrides the amount of tiles moved in each tick.
|-
| '''TAG.OVERRIDE.DOORSOUND_CLOSE
| DOORCLOSESOUND
| Overrides the sound that will be played for a door when it is being closed.
|-
| '''TAG.OVERRIDE.DOORSOUND_OPEN
| DOOROPENSOUND
| Overrides the sound that will be played for a door when it is being opened.
|-
| '''TAG.OVERRIDE.PORTCULISSOUND
| PORTCULISSOUND
| Overrides the sound that will be played for a portcullis when it is used.
|}
[[Category: Articles]]

Script Debugging

2022-08-18T19:30:07Z

Soulless:

So you've got a problem with a script and you don't know where to turn? Or everyone you've spoken to doesn't have the answers you seek? You're about to start pulling out your hair, you feel alone and lost, and no one can seem to help you. Well worry no more, you're about to help yourself! Let's talk about debugging your script

=Situations=
We'll go through some examples here to explain how one could get helpful information that will lead them to their solutions. Each situation will have it's own unique methods to help you use the tools at your disposal to fix the problem, or guide you to finding out more helpful information.

==Problems Understanding A Trigger==
Uncertain how a trigger works?

This is a great example from MalucoBeleza that illustrates the concept of logging out your results to the console for further insight into what objects a trigger is referencing. This can help you make sure that you are referencing the right object in game and that whatever follows will behave as expected.

Let's say you want to use a trigger that will fire when you kill someone, and when you kill that person you want to give the killer some experience points. You need to reference both the person being killed and the person that killed them.

The trigger in this example is [[@Kill]]. One may think that they will use the default object I as the killer and that SRC will be the person being killed. or that ACT would be the person being killed. But it is best not to assume any of these triggers will use any object reference the same as another, or even the same as a similar trigger. The best practice is to take yourself to the Spherewiki (as YOU already have) and pull up the trigger you are looking for under the Reference Compendium > [[Objects]] > [[Characters]], this will give you a very good idea of what references you can make in that trigger. Once you have that information you can begin to see what you are able to work with and how you can work with it.

As MalucoBeleza points out, this practice is required to get proper knowledge to work with a trigger

When dealing with a trigger that is new to you... its essential to check the wiki and do tests like this:

ON=@Kill
SERV.LOG NAME: <NAME>
SERV.LOG I.NAME: <I.NAME>
SERV.LOG SRC.NAME: <SRC.NAME>
SERV.LOG ARGO.NAME: <ARGO.NAME>
SERV.LOG <NAME> (<UID>) HAVE JUST KILLED <ARGO.NAME> (<ARGO>)

Debugging is also a great tool when you are performing calculations. Let’s say that you want to create your own combat system, such as:

ON=@Hit
SERV.LOG <NAME> HAVE JUST HIT <SRC.NAME>
IF (<WEAPON>)
SERV.LOG A WEAPON WAS USED: <WEAPON.NAME>
SERV.LOG <WEAPON.NAME>'S DAMAGE IS <WEAPON.DAM.LO> - <WEAPON.DAM.HI>
ELSE
SERV.LOG NO WEAPON WAS USED.
SERV.LOG <NAME>'S DAMAGE IS <DAM>
ENDIF

SERV.LOG DAMAGE STARTED AS <ARGN1>

SERV.LOG THE SKILL USED IN THIS ATTACK IS <ACTION>
IF (<ACTION> == WRESTLING) || (<ACTION> == MACEFIGHTING)
ARGN1 = <EVAL <ARGN1> + (<STR>/8)> //APPLY YOUR FORMULA HERE

ELIF (<ACTION> == ARCHERY) || (<ACTION> == FENCING)
ARGN1 = <EVAL <ARGN1> + (<DEX>/8)>

ELIF (<ACTION> == SWORDSMANSHIP)
ARGN1 = <EVAL <ARGN1> + (<DEX>/16) + (<STR>/16)>

ENDIF

SERV.LOG DAMAGE AFTER STATS BONUS ACCORDING TO THE SKILL IS <ARGN1>

IF (<SRC.ISPLAYER>) //PLAYER HITS ANOTHER PLAYER
SERV.LOG THE ARMOR OF THE DEFENDANT IS <SRC.ARMOR>
LOCAL.DAMAGE_REDUCTION = <EVAL <SRC.ARMOR>/20> //APPLY YOUR FORMULA HERE

ELSE //PLAYER HITS A NPC
SERV.LOG THE ARMOR OF THE DEFENDANT IS <SRC.AC>
LOCAL.DAMAGE_REDUCTION = <EVAL <SRC.AC>/20> //APPLY YOUR FORMULA HERE

ENDIF
ARGN1 -= <LOCAL.DAMAGE_REDUCTION>
SERV.LOG AFTER DAMAGE REDUCTION OF <LOCAL.DAMAGE_REDUCTION>, DAMAGE IS <ARGN1>

==Console Errors Regarding Scripts==
You are getting errors on your console, and it's telling you about a script but you aren't quite sure what to do. Let's see one as an example :

00:17:ERROR:(i_dye_tubs.scp,52)Range isn't closed by a '}' character.

Okay from this error we can see the filename 'i_dye_tubs' and the line number is 52. The error is that the 'Range isn't closed by a '}' character.' so let's go see what this line looks like and what we the appropriate line fix is:

So here's what line 52 from i_dye_tubs.scp looks like :
color={047e 049a

We can see above that its missing a } at the end just like the console error notified us about. The fix is to simply add the missing }.

this is a very elementary example but this explains the process of breaking down a console error. It's always the same for these script errors : "filename, line number, error description". With large complicated systems paying attention to the exact nature of your console error will guide you towards figuring out how to fix it.

Main Page

2022-08-18T15:20:34Z

Soulless:

<div style="background-color:#a7bcdc; color:#000; min-width:650px; padding:1px; text-align:center; width:100%;">
'''Starting with SphereServer'''
</div>
<div style="min-width:650px; width:100%;">
<div style="border-right:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:33%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Setup of Sphere'''
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Where to get Sphere]]
* [[Installing Sphere]]
* [[Configuring Sphere.ini]]
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Sphere 101'''
</div>
<div style="padding:0px 0px 5px 10px;">
* [[Chapter 1]] ''(Numbers, DEFNAME, ITEMDEF, CHARDEF)''
* [[Chapter 2]] ''(Sphere files explained)''
* [[Chapter 3]] ''(Scripting NPC's and items, Cool commands)''
* [[Chapter 4]] ''(Objects, operators, speech)''
* [[Chapter 5]] ''(Tags, Vars, Locals, Functions)''
* [[Chapter 6]] ''(LINKs, TIMERs, TARGETs)''
* [[Chapter 7]] ''(Loops and powerful functions)''
* [[Chapter 8]] ''(SKILLMENUs, MENUs, Gumps)''
* [[Chapter 9]] ''(Events)''
* [[Chapter 10]] ''(String Handling)''
</div>
</div>
<div style="border-left:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:67%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Extra Tutorials'''
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Common Mistakes|Common Mistakes Explained]] ''(A revision of Maximus's tutorial on the forums, and continuation of Taran's Misconceptions tutorial)''
* [[Internet and Sphere]] ''(And how to make the right use of them)''
* [[Languages Tutorial]] ''(How to script your own language system)''
* [[Making your own Skills]] ''(How to make and customize your skill)''
* [[Mul Patching Tutorial|Nazghul's Mul Patching Tutorial]] [http://sorea.profitux.cz/patching/ external link] ''(A document about mul patching and customizing your server)''
* [[Overriding Hardcoded Commands]] ''(How to override hardcoded commands and functions)''
* [[Scheduled Reboot]] ''(How to schedule system reboots)''
* [[Using MySQL]] ''(How to use MySQL)''
* [[Bitwise Operations]] ''(How to work with FLAGS/ATTR)''
* [[Script Debugging]] ''(How to fix your scripts)''
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''IMPORTANT LINKS'''
</div>
<div style="padding:0px 0px 5px 10px;">
* [https://github.com/Sphereserver SphereServer Official Github]
* [https://forum.spherecommunity.net/sshare.php?srt=4 Download Nightly Builds] ''(Plus! Extra downloads, like tools and scripts!)''
* [https://github.com/Sphereserver/Source-X/blob/master/Changelog-X1-Nightlies.txt SphereX Changelog] | [https://github.com/Sphereserver/Source/blob/master/changelog.txt 56d Changelog]
* [https://discord.gg/BZj2fEA Join us at Discord] ''(We will solve most of your doubts over there)''
</div>
</div>
</div>
.

<div style="background-color:#a7bcdc; color:#000; min-width:650px; padding:1px; text-align:center; width:100%;">
'''Reference Compendium'''
</div>
<div style="min-width:650px; width:100%;">
<div style="border-right:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:33%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Definitions|'''Definitions''']]
</div>
<div style="padding:0px 0px 5px 10px;">
* [[CHARDEF|Characters]]
* [[DIALOG|Dialogs]]
* [[EVENTS|Events]]
* [[ITEMDEF|Items]]
* [[MENU|Menus]]
* [[REGIONRESOURCE|Region Resources]]
* [[REGIONTYPE|Region Types]]
* [[AREADEF|Regions]]
* [[ROOMDEF|Rooms]]
* [[SKILLCLASS|Skill Classes]]
* [[SKILLMENU|Skill Menus]]
* [[SKILL|Skills]]
* [[SPAWN|Spawn Groups]]
* [[SPELL|Spells]]
* [[TYPEDEF|Types]]
</div>
</div>
<div style="border-left:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:67%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Objects|'''Objects''']]
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Accounts]]
* [[Characters]]
* [[Database]]
* [[Files]]
* [[GM Pages]]
* [[Items]]
** ''[[Special Items]]''
* [[Map Points]]
* [[Parties]]
* [[Regions]]
* [[Rooms]]
* [[Sectors]]
* [[Server]]
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Scripts|'''Scripts''']]
</div>
<div style="padding:0px 0px 5px 10px;">
* [[:Category:Functions|Functions and Triggers]]
* [[:Category:Variables|General Functions, Properties and References]]
* [[Intrinsic Functions]]
* [[:Category:Statements|Statements]]
* [[:Category:Triggers|Triggers]]
</div>
</div>
.
----

.
==Sphere 3rd Party Tools==
* [http://forum.spherecommunity.net/sshare.php?srt=4&uid=603 Axis II] - GM Tool for Sphere that will allow you to place objects in-game, spawns, traveling and many other useful functions for shard admins and GMs.
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=3 vSCP] - vSCP is the most complete and up-to-date syntax editor for sphere scripting. It does contain syntax highlighting, autocomplete, folding markers to specify blocks of code that can expand or collapse, bookmarks, autoindent, find/replace/gotoline, help guide for all the sphere elements added to your code, and more!
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=2 vServerLauncher] - Install and run the latest build of sphereserver in a few clicks with vServerLauncher. It's pretty quick and simple!
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=5 SphereService] - Relaunch SphereSvr.exe everytime it closes/crashes. Automatically runs at windows startup and works in a silent mode minimized to Tray.
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=4 vCrypter] - Type the client version and the tool will calculate the correct UO login keys for classic or enhanced clients.

==Other Articles==

* [[Armor Calculation]]
* [[Client Changes]]
* [[Common Scripting Misconceptions]]
* [[Custom Object Properties]]
* [[Error Codes]]
* [[Experience System]]
* [[How Combat Works]]
* [[Occam's Razor]]
* [[Optimization|Optimization Theory]]
* [[Override TAGs]]
* [[Revisions Changelog]]
* [[Sendpacket]]
* [[Skill Gain Theory]]
* [[The Process of Scripting]]
* [[Building Component Reference]]

==Credits==

'''Special thanks to:'''

[[WhoIsWho|XuN, Nolok, Ben, and Drk]], for their hard work on the X branch taking Sphere into the next decade.

[[WhoIsWho|Ben, Cloud_Br, Ellessar, Jdog, Lord Zerofiz, Mordaunt, Nazghul-ll, RanXerox, Rattlehead, Sandman, Sharlenwar, ShiryuX, thelegbra, Maximus, WarAngel and Valios]], for helping to add content.

[[WhoIsWho|Daleth]], for writing the Sphere Reference Project, and [[WhoIsWho|Mordaunt]] for converting it to .chm format.

[[WhoIsWho|Tracker]], for writing the Sphere 56 Tracking Changes in Sphereserver.net

[[WhoIsWho|Taran]], for writing the original and now famous Sphere Scripting for Dummies tutorials, and [[WhoIsWho|MrSugarCube]] for bringing it up-to-date directly from source.

[[WhoIsWho|Ben, Khaos, Ranxerox, Shiryux, Furio, Radiant, Vjaka, Nazghul-ll, Ellessar, Torfo, Shadow Dragon, MrSugarCube and coruja747]] for continuing to develop Sphere into a powerful and very customizable Ultima Online emulator.

[[WhoIsWho|Crius]], for providing hosting for the original SphereWiki, and [[WhoIsWho|Torfo]] for providing the current hosting.

==External Links==

* [[Useful Links]] ''(An ongoing list of useful links for community members)''
* [http://www.spherecommunity.net/ Official SphereServer Website]
* [https://forum.spherecommunity.net/sshare.php?srt=4 Nightly builds]
* [http://nightly.prerelease.sphere.torfo.org/ Nightly builds - OUTDATED, use the link above]
* [http://spherepack.codeplex.com/ Sphere Community Pack 2.0]
* [http://uo.torfo.org/packetguide/ Jerrith's UO Packet Guide]
* [http://uo.torfo.org/packetguideKR/ Wyatt&Kons's UOKR Packet Guide]

[[Category: Navigation]]

Main Page

2022-08-18T15:19:28Z

Soulless:

<div style="background-color:#a7bcdc; color:#000; min-width:650px; padding:1px; text-align:center; width:100%;">
'''Starting with SphereServer'''
</div>
<div style="min-width:650px; width:100%;">
<div style="border-right:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:33%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Setup of Sphere'''
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Where to get Sphere]]
* [[Installing Sphere]]
* [[Configuring Sphere.ini]]
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Sphere 101'''
</div>
<div style="padding:0px 0px 5px 10px;">
* [[Chapter 1]] ''(Numbers, DEFNAME, ITEMDEF, CHARDEF)''
* [[Chapter 2]] ''(Sphere files explained)''
* [[Chapter 3]] ''(Scripting NPC's and items, Cool commands)''
* [[Chapter 4]] ''(Objects, operators, speech)''
* [[Chapter 5]] ''(Tags, Vars, Locals, Functions)''
* [[Chapter 6]] ''(LINKs, TIMERs, TARGETs)''
* [[Chapter 7]] ''(Loops and powerful functions)''
* [[Chapter 8]] ''(SKILLMENUs, MENUs, Gumps)''
* [[Chapter 9]] ''(Events)''
* [[Chapter 10]] ''(String Handling)''
</div>
</div>
<div style="border-left:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:67%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Extra Tutorials'''
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Common Mistakes|Common Mistakes Explained]] ''(A revision of Maximus's tutorial on the forums, and continuation of Taran's Misconceptions tutorial)''
* [[Internet and Sphere]] ''(And how to make the right use of them)''
* [[Languages Tutorial]] ''(How to script your own language system)''
* [[Making your own Skills]] ''(How to make and customize your skill)''
* [[Mul Patching Tutorial|Nazghul's Mul Patching Tutorial]] [http://sorea.profitux.cz/patching/ external link] ''(A document about mul patching and customizing your server)''
* [[Overriding Hardcoded Commands]] ''(How to override hardcoded commands and functions)''
* [[Scheduled Reboot]] ''(How to schedule system reboots)''
* [[Using MySQL]] ''(How to use MySQL)''
* [[Bitwise Operations]] ''(How to work with FLAGS/ATTR)''
* [[Script Debugging]] ''(How to fix your scripts)''
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''IMPORTANT LINKS'''
</div>
<div style="padding:0px 0px 5px 10px;">
* [https://github.com/Sphereserver SphereServer Official Github]
* [https://forum.spherecommunity.net/sshare.php?srt=4 Download Nightly Builds] ''(Plus! Extra downloads, like tools and scripts!)''
* [https://github.com/Sphereserver/Source-X/blob/master/Changelog-X1-Nightlies.txt SphereX Changelog] | [https://github.com/Sphereserver/Source/blob/master/changelog.txt 56d Changelog]
* [https://discord.gg/BZj2fEA Join us at Discord] ''(We will solve most of your doubts over there)''
* [[Useful Links]] ''(An ongoing list of useful links for community members)''
</div>
</div>
</div>
.

<div style="background-color:#a7bcdc; color:#000; min-width:650px; padding:1px; text-align:center; width:100%;">
'''Reference Compendium'''
</div>
<div style="min-width:650px; width:100%;">
<div style="border-right:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:33%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Definitions|'''Definitions''']]
</div>
<div style="padding:0px 0px 5px 10px;">
* [[CHARDEF|Characters]]
* [[DIALOG|Dialogs]]
* [[EVENTS|Events]]
* [[ITEMDEF|Items]]
* [[MENU|Menus]]
* [[REGIONRESOURCE|Region Resources]]
* [[REGIONTYPE|Region Types]]
* [[AREADEF|Regions]]
* [[ROOMDEF|Rooms]]
* [[SKILLCLASS|Skill Classes]]
* [[SKILLMENU|Skill Menus]]
* [[SKILL|Skills]]
* [[SPAWN|Spawn Groups]]
* [[SPELL|Spells]]
* [[TYPEDEF|Types]]
</div>
</div>
<div style="border-left:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:67%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Objects|'''Objects''']]
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Accounts]]
* [[Characters]]
* [[Database]]
* [[Files]]
* [[GM Pages]]
* [[Items]]
** ''[[Special Items]]''
* [[Map Points]]
* [[Parties]]
* [[Regions]]
* [[Rooms]]
* [[Sectors]]
* [[Server]]
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Scripts|'''Scripts''']]
</div>
<div style="padding:0px 0px 5px 10px;">
* [[:Category:Functions|Functions and Triggers]]
* [[:Category:Variables|General Functions, Properties and References]]
* [[Intrinsic Functions]]
* [[:Category:Statements|Statements]]
* [[:Category:Triggers|Triggers]]
</div>
</div>
.
----

.
==Sphere 3rd Party Tools==
* [http://forum.spherecommunity.net/sshare.php?srt=4&uid=603 Axis II] - GM Tool for Sphere that will allow you to place objects in-game, spawns, traveling and many other useful functions for shard admins and GMs.
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=3 vSCP] - vSCP is the most complete and up-to-date syntax editor for sphere scripting. It does contain syntax highlighting, autocomplete, folding markers to specify blocks of code that can expand or collapse, bookmarks, autoindent, find/replace/gotoline, help guide for all the sphere elements added to your code, and more!
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=2 vServerLauncher] - Install and run the latest build of sphereserver in a few clicks with vServerLauncher. It's pretty quick and simple!
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=5 SphereService] - Relaunch SphereSvr.exe everytime it closes/crashes. Automatically runs at windows startup and works in a silent mode minimized to Tray.
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=4 vCrypter] - Type the client version and the tool will calculate the correct UO login keys for classic or enhanced clients.

==Other Articles==

* [[Armor Calculation]]
* [[Client Changes]]
* [[Common Scripting Misconceptions]]
* [[Custom Object Properties]]
* [[Error Codes]]
* [[Experience System]]
* [[How Combat Works]]
* [[Occam's Razor]]
* [[Optimization|Optimization Theory]]
* [[Override TAGs]]
* [[Revisions Changelog]]
* [[Sendpacket]]
* [[Skill Gain Theory]]
* [[The Process of Scripting]]
* [[Building Component Reference]]

==Credits==

'''Special thanks to:'''

[[WhoIsWho|XuN, Nolok, Ben, and Drk]], for their hard work on the X branch taking Sphere into the next decade.

[[WhoIsWho|Ben, Cloud_Br, Ellessar, Jdog, Lord Zerofiz, Mordaunt, Nazghul-ll, RanXerox, Rattlehead, Sandman, Sharlenwar, ShiryuX, thelegbra, Maximus, WarAngel and Valios]], for helping to add content.

[[WhoIsWho|Daleth]], for writing the Sphere Reference Project, and [[WhoIsWho|Mordaunt]] for converting it to .chm format.

[[WhoIsWho|Tracker]], for writing the Sphere 56 Tracking Changes in Sphereserver.net

[[WhoIsWho|Taran]], for writing the original and now famous Sphere Scripting for Dummies tutorials, and [[WhoIsWho|MrSugarCube]] for bringing it up-to-date directly from source.

[[WhoIsWho|Ben, Khaos, Ranxerox, Shiryux, Furio, Radiant, Vjaka, Nazghul-ll, Ellessar, Torfo, Shadow Dragon, MrSugarCube and coruja747]] for continuing to develop Sphere into a powerful and very customizable Ultima Online emulator.

[[WhoIsWho|Crius]], for providing hosting for the original SphereWiki, and [[WhoIsWho|Torfo]] for providing the current hosting.

==External Links==

* [http://www.spherecommunity.net/ Official SphereServer Website]
* [https://forum.spherecommunity.net/sshare.php?srt=4 Nightly builds]
* [http://nightly.prerelease.sphere.torfo.org/ Nightly builds - OUTDATED, use the link above]
* [http://spherepack.codeplex.com/ Sphere Community Pack 2.0]
* [http://uo.torfo.org/packetguide/ Jerrith's UO Packet Guide]
* [http://uo.torfo.org/packetguideKR/ Wyatt&Kons's UOKR Packet Guide]

[[Category: Navigation]]

Main Page

2022-08-18T15:18:48Z

Soulless:

<div style="background-color:#a7bcdc; color:#000; min-width:650px; padding:1px; text-align:center; width:100%;">
'''Starting with SphereServer'''
</div>
<div style="min-width:650px; width:100%;">
<div style="border-right:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:33%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Setup of Sphere'''
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Where to get Sphere]]
* [[Installing Sphere]]
* [[Configuring Sphere.ini]]
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Sphere 101'''
</div>
<div style="padding:0px 0px 5px 10px;">
* [[Chapter 1]] ''(Numbers, DEFNAME, ITEMDEF, CHARDEF)''
* [[Chapter 2]] ''(Sphere files explained)''
* [[Chapter 3]] ''(Scripting NPC's and items, Cool commands)''
* [[Chapter 4]] ''(Objects, operators, speech)''
* [[Chapter 5]] ''(Tags, Vars, Locals, Functions)''
* [[Chapter 6]] ''(LINKs, TIMERs, TARGETs)''
* [[Chapter 7]] ''(Loops and powerful functions)''
* [[Chapter 8]] ''(SKILLMENUs, MENUs, Gumps)''
* [[Chapter 9]] ''(Events)''
* [[Chapter 10]] ''(String Handling)''
</div>
</div>
<div style="border-left:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:67%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''Extra Tutorials'''
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Common Mistakes|Common Mistakes Explained]] ''(A revision of Maximus's tutorial on the forums, and continuation of Taran's Misconceptions tutorial)''
* [[Internet and Sphere]] ''(And how to make the right use of them)''
* [[Languages Tutorial]] ''(How to script your own language system)''
* [[Making your own Skills]] ''(How to make and customize your skill)''
* [[Mul Patching Tutorial|Nazghul's Mul Patching Tutorial]] [http://sorea.profitux.cz/patching/ external link] ''(A document about mul patching and customizing your server)''
* [[Overriding Hardcoded Commands]] ''(How to override hardcoded commands and functions)''
* [[Scheduled Reboot]] ''(How to schedule system reboots)''
* [[Using MySQL]] ''(How to use MySQL)''
* [[Bitwise Operations]] ''(How to work with FLAGS/ATTR)''
* [[Script Debugging]] ''(How to fix your scripts)''
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
'''IMPORTANT LINKS'''
</div>
<div style="padding:0px 0px 5px 10px;">
* [https://github.com/Sphereserver SphereServer Official Github]
* [https://forum.spherecommunity.net/sshare.php?srt=4 Download Nightly Builds] ''(Plus! Extra downloads, like tools and scripts!)''
* [https://github.com/Sphereserver/Source-X/blob/master/Changelog-X1-Nightlies.txt SphereX Changelog] | [https://github.com/Sphereserver/Source/blob/master/changelog.txt 56d Changelog]
* [https://discord.gg/BZj2fEA Join us at Discord] ''(We will solve most of your doubts over there)''
</div>
</div>
</div>
.

<div style="background-color:#a7bcdc; color:#000; min-width:650px; padding:1px; text-align:center; width:100%;">
'''Reference Compendium'''
</div>
<div style="min-width:650px; width:100%;">
<div style="border-right:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:33%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Definitions|'''Definitions''']]
</div>
<div style="padding:0px 0px 5px 10px;">
* [[CHARDEF|Characters]]
* [[DIALOG|Dialogs]]
* [[EVENTS|Events]]
* [[ITEMDEF|Items]]
* [[MENU|Menus]]
* [[REGIONRESOURCE|Region Resources]]
* [[REGIONTYPE|Region Types]]
* [[AREADEF|Regions]]
* [[ROOMDEF|Rooms]]
* [[SKILLCLASS|Skill Classes]]
* [[SKILLMENU|Skill Menus]]
* [[SKILL|Skills]]
* [[SPAWN|Spawn Groups]]
* [[SPELL|Spells]]
* [[TYPEDEF|Types]]
</div>
</div>
<div style="border-left:1px solid #a7bcdc; float:left; height:100%; margin-right:-1px; width:67%;">
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Objects|'''Objects''']]
</div>
<div style="border-bottom:1px solid #a7bcdc; padding:0px 0px 5px 10px;">
* [[Accounts]]
* [[Characters]]
* [[Database]]
* [[Files]]
* [[GM Pages]]
* [[Items]]
** ''[[Special Items]]''
* [[Map Points]]
* [[Parties]]
* [[Regions]]
* [[Rooms]]
* [[Sectors]]
* [[Server]]
</div>
<div style="border-bottom:1px solid #a7bcdc; color:#a7bcdc; font-size:18px; padding-left:10px;">
[[:Category:Scripts|'''Scripts''']]
</div>
<div style="padding:0px 0px 5px 10px;">
* [[:Category:Functions|Functions and Triggers]]
* [[:Category:Variables|General Functions, Properties and References]]
* [[Intrinsic Functions]]
* [[:Category:Statements|Statements]]
* [[:Category:Triggers|Triggers]]
</div>
</div>
.
----

.
==Sphere 3rd Party Tools==
* [http://forum.spherecommunity.net/sshare.php?srt=4&uid=603 Axis II] - GM Tool for Sphere that will allow you to place objects in-game, spawns, traveling and many other useful functions for shard admins and GMs.
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=3 vSCP] - vSCP is the most complete and up-to-date syntax editor for sphere scripting. It does contain syntax highlighting, autocomplete, folding markers to specify blocks of code that can expand or collapse, bookmarks, autoindent, find/replace/gotoline, help guide for all the sphere elements added to your code, and more!
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=2 vServerLauncher] - Install and run the latest build of sphereserver in a few clicks with vServerLauncher. It's pretty quick and simple!
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=5 SphereService] - Relaunch SphereSvr.exe everytime it closes/crashes. Automatically runs at windows startup and works in a silent mode minimized to Tray.
* [http://forum.spherecommunity.net/sshare.php?srt=4&prj=4 vCrypter] - Type the client version and the tool will calculate the correct UO login keys for classic or enhanced clients.

==Other Articles==

* [[Armor Calculation]]
* [[Client Changes]]
* [[Common Scripting Misconceptions]]
* [[Custom Object Properties]]
* [[Error Codes]]
* [[Experience System]]
* [[How Combat Works]]
* [[Occam's Razor]]
* [[Optimization|Optimization Theory]]
* [[Override TAGs]]
* [[Revisions Changelog]]
* [[Sendpacket]]
* [[Skill Gain Theory]]
* [[The Process of Scripting]]
* [[Building Component Reference]]

==Credits==

'''Special thanks to:'''

[[WhoIsWho|XuN, Nolok, Ben, and Drk]], for their hard work on the X branch taking Sphere into the next decade.

[[WhoIsWho|Ben, Cloud_Br, Ellessar, Jdog, Lord Zerofiz, Mordaunt, Nazghul-ll, RanXerox, Rattlehead, Sandman, Sharlenwar, ShiryuX, thelegbra, Maximus, WarAngel and Valios]], for helping to add content.

[[WhoIsWho|Daleth]], for writing the Sphere Reference Project, and [[WhoIsWho|Mordaunt]] for converting it to .chm format.

[[WhoIsWho|Tracker]], for writing the Sphere 56 Tracking Changes in Sphereserver.net

[[WhoIsWho|Taran]], for writing the original and now famous Sphere Scripting for Dummies tutorials, and [[WhoIsWho|MrSugarCube]] for bringing it up-to-date directly from source.

[[WhoIsWho|Ben, Khaos, Ranxerox, Shiryux, Furio, Radiant, Vjaka, Nazghul-ll, Ellessar, Torfo, Shadow Dragon, MrSugarCube and coruja747]] for continuing to develop Sphere into a powerful and very customizable Ultima Online emulator.

[[WhoIsWho|Crius]], for providing hosting for the original SphereWiki, and [[WhoIsWho|Torfo]] for providing the current hosting.

==External Links==

* [http://www.spherecommunity.net/ Official SphereServer Website]
* [https://forum.spherecommunity.net/sshare.php?srt=4 Nightly builds]
* [http://nightly.prerelease.sphere.torfo.org/ Nightly builds - OUTDATED, use the link above]
* [http://spherepack.codeplex.com/ Sphere Community Pack 2.0]
* [http://uo.torfo.org/packetguide/ Jerrith's UO Packet Guide]
* [http://uo.torfo.org/packetguideKR/ Wyatt&Kons's UOKR Packet Guide]

[[Category: Navigation]]

Useful Links

2022-08-18T15:18:06Z

Soulless:

Modern SphereServer Nightly Downloads (Server) https://forum.spherecommunity.net/sshare.php?srt=4

Older/Classic SphereServer downloads (Server) https://forum.spherecommunity.net/sshare.php?srt=4&prj=7

Sphere-X Script Pack (Scripts) https://github.com/cbnolok/SphereX-Scriptpack

Julians Script Vault (Scripts) https://github.com/JulianUO/SphereX-ScriptsVault

List of UO Packets (Info) https://docs.polserver.com/packets/index.php

Ultima Online Downloads (Clients) https://mega.nz/folder/6uYxnIpY#tahGzzz_yOkLgNM1c_DxdQ

Axis 2 Downloads (GM tool) https://forum.spherecommunity.net/sshare.php?srt=4&prj=1

Leviathan (GM tool) https://github.com/cbnolok/Leviathan/releases/download/v0.4.3/LeviathanWin64-automated-v0.4.3.zip

CentrED (Worldbuilding) https://uo.wzk.cz/centred/

UO-Pixel (Graphics) http://www.uo-pixel.de/

UO Fiddler ( MUL Viewer) http://uofiddler.polserver.com/

UO Grafiken by Nyray (Graphics) https://nyray.wordpress.com/

Vestimisu (Graphics) http://vestimisu.blogspot.com/

Ultima Online Graphics By Rubra (Graphcs) http://uographicsrubra.blogspot.com/

Isis‘ UO Grafiken (Graphics) https://isispixel.wordpress.com/

ServUO (Graphics) https://www.servuo.com/archive/categories/assets.13/

UOGateway (Shard Listing) https://uogateway.com/

Useful Links

2022-08-18T15:17:50Z

Soulless: Created page with "Modern SphereServer Nightly Downloads (Server) https://forum.spherecommunity.net/sshare.php?srt=4 Older/Classic SphereServer downloads (Server) https://forum.spherecommunity.n..."

Modern SphereServer Nightly Downloads (Server) https://forum.spherecommunity.net/sshare.php?srt=4
Older/Classic SphereServer downloads (Server) https://forum.spherecommunity.net/sshare.php?srt=4&prj=7
Sphere-X Script Pack (Scripts) https://github.com/cbnolok/SphereX-Scriptpack
Julians Script Vault (Scripts) https://github.com/JulianUO/SphereX-ScriptsVault
List of UO Packets (Info) https://docs.polserver.com/packets/index.php
Ultima Online Downloads (Clients) https://mega.nz/folder/6uYxnIpY#tahGzzz_yOkLgNM1c_DxdQ
Axis 2 Downloads (GM tool) https://forum.spherecommunity.net/sshare.php?srt=4&prj=1
Leviathan (GM tool) https://github.com/cbnolok/Leviathan/releases/download/v0.4.3/LeviathanWin64-automated-v0.4.3.zip
CentrED (Worldbuilding) https://uo.wzk.cz/centred/
UO-Pixel (Graphics) http://www.uo-pixel.de/
UO Fiddler ( MUL Viewer) http://uofiddler.polserver.com/
UO Grafiken by Nyray (Graphics) https://nyray.wordpress.com/
Vestimisu (Graphics) http://vestimisu.blogspot.com/
Ultima Online Graphics By Rubra (Graphcs) http://uographicsrubra.blogspot.com/
Isis‘ UO Grafiken (Graphics) https://isispixel.wordpress.com/
ServUO (Graphics) https://www.servuo.com/archive/categories/assets.13/
UOGateway (Shard Listing) https://uogateway.com/

Script Debugging

2022-08-18T15:16:38Z

Soulless: /* Examples */

So you've got a problem with a script and you don't know where to turn? Or everyone you've spoken to doesn't have the answers you seek? You're about to start pulling out your hair, you feel alone and lost, and no one can seem to help you. Well worry no more, you're about to help yourself! Let's talk about debugging your script

=Situations=
We'll go through some examples here to explain how one could get helpful information that will lead them to their solutions. Each situation will have it's own unique methods to help you use the tools at your disposal to fix the problem, or guide you to finding out more helpful information.

==Problems Understanding A Trigger==
Uncertain how a trigger works?

This is a great example from MalucoBeleza that illustrates the concept of logging out your results to the console for further insight into what objects a trigger is referencing. This can help you make sure that you are referencing the right object in game and that whatever follows will behave as expected.

Let's say you want to use a trigger that will fire when you kill someone, and when you kill that person you want to give the killer some experience points. You need to reference both the person being killed and the person that killed them.

The trigger in this example is [[@Kill]]. One may think that they will use the default object I as the killer and that SRC will be the person being killed. or that ACT would be the person being killed. But it is best not to assume any of these triggers will use any object reference the same as another, or even the same as a similar trigger. The best practice is to take yourself to the Spherewiki (as YOU already have) and pull up the trigger you are looking for under the Reference Compendium > [[Objects]] > [[Characters]], this will give you a very good idea of what references you can make in that trigger. Once you have that information you can begin to see what you are able to work with and how you can work with it.

As MalucoBeleza points out, this practice is required to get proper knowledge to work with a trigger

When dealing with a trigger that is new to you... its essential to check the wiki and do tests like this:

ON=@Kill
SERV.LOG NAME: <NAME>
SERV.LOG I.NAME: <I.NAME>
SERV.LOG SRC.NAME: <SRC.NAME>
SERV.LOG ARGO.NAME: <ARGO.NAME>
SERV.LOG <NAME> (<UID>) HAVE JUST KILLED <ARGO.NAME> (<ARGO>)

==Console Errors Regarding Scripts==
You are getting errors on your console, and it's telling you about a script but you aren't quite sure what to do. Let's see one as an example :

00:17:ERROR:(i_dye_tubs.scp,52)Range isn't closed by a '}' character.

Okay from this error we can see the filename 'i_dye_tubs' and the line number is 52. The error is that the 'Range isn't closed by a '}' character.' so let's go see what this line looks like and what we the appropriate line fix is:

So here's what line 52 from i_dye_tubs.scp looks like :
color={047e 049a

We can see above that its missing a } at the end just like the console error notified us about. The fix is to simply add the missing }.

this is a very elementary example but this explains the process of breaking down a console error. It's always the same for these script errors : "filename, line number, error description". With large complicated systems paying attention to the exact nature of your console error will guide you towards figuring out how to fix it.

Script Debugging

2022-08-18T14:47:17Z

Soulless: /* Problems Understanding A Trigger */

Script Debugging

2022-08-18T14:46:57Z