Added https://github.com/pret/pokeemerald/compare/master...LOuroboros:pokeemerald:getObjFacingDir

Useful-Scripting-Specials.md

@@ -11,6 +11,7 @@ All specials need to be added to the table in `data/specials.inc` following othe
 - [Set Seen/Caught Mon](#setseenmon-and-setcaughtmon)
 - [Set Mon Ball](#setmonball)
 - [Check For Species](#checkforspecies)
+- [Get An Object's Facing Direction](#getobjectfacingdirection)
 
 ### getobjectposition
 
@@ -278,3 +279,81 @@ Route101_EventScript_Text_NoTorchic:
 Route101_EventScript_Text_HasTorchic:
     .string "You have a TORCHIC!$"
 ```
+
+### getobjectfacingdirection
+
+Credits to Lunos.
+
+This command will let you check the direction at which an object event on a map is facing, which in turn allows you to handle edge cases in overworld scripts that deal with lots of movement.
+
+1. First, our scripting macro:
+
+```c
+    @ Gets the facing direction of a given event object and stores it in the variable \dest.
+    .macro getobjectfacingdirection evObjId:req, dest:req
+    setvar \dest, \evObjId
+    specialvar \dest, Script_GetObjectFacingDirection
+    .endm
+```
+
+2. Next, a special function that will return the facing direction of the event object whose Local ID *(i.e. the object's ID on the current map)* is stored in [the temporary variable](https://github.com/pret/pokeemerald/blob/master/include/constants/vars.h#L6-L7) `VAR_TEMP_1`
+
+```c
+u8 Script_GetObjectFacingDirection(void)
+{
+    u8 objId = GetObjectEventIdByLocalId(VarGet(VAR_TEMP_1));
+    return gObjectEvents[objId].facingDirection;
+}
+```
+
+And we're done.
+
+This macro is as easy to use as the other ones in this document.
+
+You just invoke `getobjectfacingdirection`, feed it an event object's Local ID and then a variable to store their facing directon.
+
+Here's a quick example of its usage:
+
+```
+Route101_EventScript_RouteSign::
+    getobjectfacingdirection OBJ_EVENT_ID_PLAYER, VAR_TEMP_1
+    goto_if_eq VAR_TEMP_1, DIR_NORTH, Route101_EventScript_RouteSign_North
+    goto_if_eq VAR_TEMP_1, DIR_SOUTH, Route101_EventScript_RouteSign_South
+    goto_if_eq VAR_TEMP_1, DIR_WEST, Route101_EventScript_RouteSign_West
+    goto_if_eq VAR_TEMP_1, DIR_EAST, Route101_EventScript_RouteSign_East
+    end
+
+Route101_EventScript_RouteSign_North:
+    msgbox Route101_Text_RouteSign_North, MSGBOX_DEFAULT
+    release
+    end
+
+Route101_EventScript_RouteSign_South:
+    msgbox Route101_Text_RouteSign_South, MSGBOX_DEFAULT
+    release
+    end
+
+Route101_EventScript_RouteSign_West:
+    msgbox Route101_Text_RouteSign_West, MSGBOX_DEFAULT
+    release
+    end
+
+Route101_EventScript_RouteSign_East:
+    msgbox Route101_Text_RouteSign_East, MSGBOX_DEFAULT
+    release
+    end
+
+Route101_Text_RouteSign_North:
+    .string "The Player is facing North!$"
+
+Route101_Text_RouteSign_South:
+    .string "The Player is facing South!$"
+
+Route101_Text_RouteSign_West:
+    .string "The Player is facing West!$"
+
+Route101_Text_RouteSign_East:
+    .string "The Player is facing East!$"
+```
+
+![mGBA_20221107_192254264](https://user-images.githubusercontent.com/4485172/200428501-11075a22-41d5-4a69-b08d-46d4913d5280.gif)