Created Useful Scripting Specials (markdown)

Useful-Scripting-Specials.md

@@ -0,0 +1,55 @@
+## Useful Scripting Specials/Macros
+
+This page will add some new scripting commands that may be useful for developing more advanced scripts.
+
+### getobjectposition
+
+credits to ghoulslash
+
+This command will get either the map template position, or the current position of any object.
+
+1. First, our scripting macro:
+
+```c
+@ return current (posType = 0) or map (posType = 1) position of object to VAR_0x8007 (x), VAR_0x8008 (y)
+.macro getobjectxy localId:req, posType:req
+setvar VAR_0x8000, \localId
+setvar VAR_0x8001, \posType
+special GetObjectPosition
+.endm
+```
+
+2. Next, our special. You can add this to any .c file, I suggest src/event_object_movement or src/field_specials.c
+```c
+// get position (0 for current, 1 for map) of object event, return to VAR_0x8007, VAR_0x8008
+void GetObjectPosition(void)
+{
+    u16 localId      = gSpecialVar_0x8000;
+    u16 useTemplate  = gSpecialVar_0x8001;
+
+    u16 *x = &gSpecialVar_0x8007;
+    u16 *y = &gSpecialVar_0x8008;
+
+    if (!useTemplate)
+    {
+        /* current position */
+        const u16 objId = GetObjectEventIdByLocalIdIncludeInactive(localId);
+        const struct ObjectEvent *objEvent = &gObjectEvents[objId];
+        *x = objEvent->currentCoords.x - 7; // subtract out camera size
+        *y = objEvent->currentCoords.y - 7;
+    }
+    else
+    {
+        const struct ObjectEventTemplate *objTemplate =
+            FindObjectEventTemplateByLocalId(localId,
+                    gSaveBlock1Ptr->objectEventTemplates,
+                    gMapHeader.events->objectEventCount);
+        *x = objTemplate->x;
+        *y = objTemplate->y;
+    }
+}
+```
+
+3. Finally, add our new special to the specials table in `data/specials.inc`
+
+`def_special GetObjectPosition`