Code edits in FalloutEngine.cpp

Added comments to some defines in Define.h.

sfall/Define.h

@@ -202,29 +202,29 @@ enum Material : long
 
 namespace ObjectFlag {
 	enum ObjectFlag : DWORD {
-		Mouse_3d = 0x1,
-		WalkThru = 0x4,
-		Flat = 0x8,
-		NoBlock = 0x10,
-		Lighting = 0x20,
-		Temp = 0x400,
-		MultiHex = 0x800,
-		NoHighlight = 0x1000,
-		Used = 0x2000,
-		TransRed = 0x4000,
-		TransNone = 0x8000,
-		TransWall = 0x10000,
-		TransGlass = 0x20000,
-		TransSteam = 0x40000,
-		TransEnergy = 0x80000,
-		Left_Hand = 0x1000000,
-		Right_Hand = 0x2000000,
-		Worn = 0x4000000,
-		HiddenItem = 0x8000000,
+		Mouse_3d     = 0x1,
+		WalkThru     = 0x4,
+		Flat         = 0x8,
+		NoBlock      = 0x10,
+		Lighting     = 0x20,
+		Temp         = 0x400,
+		MultiHex     = 0x800,
+		NoHighlight  = 0x1000,
+		Used         = 0x2000,
+		TransRed     = 0x4000,
+		TransNone    = 0x8000,
+		TransWall    = 0x10000,
+		TransGlass   = 0x20000,
+		TransSteam   = 0x40000,
+		TransEnergy  = 0x80000,
+		Left_Hand    = 0x1000000,
+		Right_Hand   = 0x2000000,
+		Worn         = 0x4000000,
+		HiddenItem   = 0x8000000,
 		WallTransEnd = 0x10000000,
-		LightThru = 0x20000000,
-		Seen = 0x40000000,
-		ShootThru = 0x80000000,
+		LightThru    = 0x20000000,
+		Seen         = 0x40000000,
+		ShootThru    = 0x80000000,
 	};
 }
 
@@ -274,7 +274,7 @@ enum ProtoId : long
 //XXXXXXXXXXXXXXXXXXXXX
 
 // Trait defines //
-#define TRAIT_PERK  (0)
+#define TRAIT_PERK   (0)
 #define TRAIT_OBJECT (1)
 #define TRAIT_TRAIT  (2)
 
@@ -475,10 +475,10 @@ enum Stat : long
 	STAT_rad_resist = 31,
 	STAT_poison_resist = 32,
 	// poison_resist MUST be the last derived stat
-	// nonderived stats
+	// non-derived stats
 	STAT_age = 33,
 	STAT_gender = 34,
-	// gender MUST be the last nonderived stat
+	// gender MUST be the last non-derived stat
 	STAT_current_hp = 35,
 	STAT_current_poison = 36,
 	STAT_current_rad = 37,
@@ -683,6 +683,13 @@ enum RollResult
 	ROLL_CRITICAL_SUCCESS = 0x3,
 };
 
+enum CombatStateFlag : long
+{
+	in_combat          = 1,
+	enemy_out_of_range = 2,
+	is_fleeing         = 4,
+};
+
 namespace Fields {
 	enum CommonObj : long
 	{
@@ -750,13 +757,14 @@ namespace WinFlags {
 namespace AIpref {
 	enum distance : long
 	{
-		DIST_stay_close              = 0,
-		DIST_charge                  = 1,
-		DIST_snipe                   = 2,
-		DIST_on_your_own             = 3,
-		DIST_stay                    = 4
+		DIST_stay_close              = 0, // the attacker will stay at a distance no more than 5 hexes from the player (defined in ai_move_steps_closer, cai_perform_distance_prefs)
+		DIST_charge                  = 1, // AI will always try to get close to its target before or after attack
+		DIST_snipe                   = 2, // when the distance between the attacker and the target decreases, the attacker will try to move away from the target to a distance of up to 10 hexes
+		DIST_on_your_own             = 3, // no special behavior defined for this
+		DIST_stay                    = 4  // the attacker will, if possible, stay at the hex where the combat started (defined in ai_move_steps_closer, ai_move_away)
 	};
 
+	// presets for party members
 	enum disposition : long
 	{
 		DISP_none                    = -1,
@@ -769,11 +777,11 @@ namespace AIpref {
 
 	enum attack_who : long
 	{
-		ATKWHO_whomever_attacking_me = 0,
-		ATKWHO_strongest             = 1,
-		ATKWHO_weakest               = 2,
-		ATKWHO_whomever              = 3,
-		ATKWHO_closest               = 4,
+		ATKWHO_whomever_attacking_me = 0, // attack the target that the player is attacking (only for party members)
+		ATKWHO_strongest             = 1, // attack stronger targets (will switch to stronger ones in combat)
+		ATKWHO_weakest               = 2, // attack weaker targets
+		ATKWHO_whomever              = 3, // anyone
+		ATKWHO_closest               = 4, // only attack near targets
 	};
 
 	enum run_away_mode : long
@@ -795,13 +803,13 @@ namespace AIpref {
 		WEAPON_ranged_over_melee     = 3,
 		WEAPON_ranged                = 4,
 		WEAPON_unarmed               = 5,
-		WEAPON_unarmed_over_thrown   = 6, // not available in party member control panel
-		WEAPON_random                = 7  // not available in party member control panel
+		WEAPON_unarmed_over_thrown   = 6, // not available for party member in control panel
+		WEAPON_random                = 7  // not available for party member in control panel
 	};
 
 	enum area_attack_mode : long
 	{
-		AREA_no_pref                 = -1, // special logic for NPC (not available in party member control panel)
+		AREA_no_pref                 = -1, // special logic for NPC (not available for party member in control panel)
 		AREA_always                  = 0,
 		AREA_sometimes               = 1,  // use random value from cap.secondary_freq
 		AREA_be_sure                 = 2,  // 85% hit chance

sfall/FalloutEngine.cpp

@@ -512,7 +512,7 @@ const char* GetMessageStr(const MSGList* fileAddr, long messageId) {
 	return fo_getmsg(fileAddr, &messageBuf, messageId);
 }
 
-const char* MsgSearch(const MSGList* fileAddr, long messageId) {
+const char* MessageSearch(const MSGList* fileAddr, long messageId) {
 	messageBuf.number = messageId;
 	if (fo_message_search(fileAddr, &messageBuf) == 1) {
 		return messageBuf.message;
@@ -520,7 +520,7 @@ const char* MsgSearch(const MSGList* fileAddr, long messageId) {
 	return nullptr;
 }
 
-Queue* QueueFindUtil(TGameObj* object, long type) {
+Queue* QueueFind(TGameObj* object, long type) {
 	if (*ptr_queue) {
 		Queue* queue = *ptr_queue;
 		while (queue->object != object && queue->type != type) {
@@ -534,20 +534,16 @@ Queue* QueueFindUtil(TGameObj* object, long type) {
 
 long AnimCodeByWeapon(TGameObj* weapon) {
 	if (weapon != nullptr) {
-		sProto* proto = GetProto(weapon->protoId);
-		if (proto != nullptr && proto->item.type == item_type_weapon) {
+		sProto* proto = nullptr;
+		if (GetProto(weapon->protoId, proto) && proto->item.type == item_type_weapon) {
 			return proto->item.weapon.animationCode;
 		}
 	}
 	return 0;
 }
 
-sProto* GetProto(long pid) {
-	sProto* protoPtr;
-	if (fo_proto_ptr(pid, &protoPtr) != -1) {
-		return protoPtr;
-	}
-	return nullptr;
+bool GetProto(long pid, sProto* outProto) {
+	return (fo_proto_ptr(pid, &outProto) != -1);
 }
 
 void SkillGetTags(long* result, long num) {

sfall/FalloutEngine.h

@@ -500,15 +500,22 @@ __forceinline void sf_rect_free(RectList* rect) {
 const char* GetMessageStr(const MSGList* fileAddr, long messageId);
 
 // similar to GetMessageStr, but returns nullptr when no message is found
-const char* MsgSearch(const MSGList* fileAddr, long messageId);
+const char* MessageSearch(const MSGList* fileAddr, long messageId);
 
-Queue* QueueFindUtil(TGameObj* object, long type);
+Queue* QueueFind(TGameObj* object, long type);
 
 // returns weapon animation code
 long AnimCodeByWeapon(TGameObj* weapon);
 
-// returns pointer to prototype by PID, or nullptr on failure
-sProto* GetProto(long pid);
+// returns False if the prototype does not exist, or pointer to prototype by PID in the outProto argument
+bool GetProto(long pid, sProto* outProto);
+
+// returns pointer to prototype by PID, or nullptr on get failure
+// NOTE: not an efficient construction
+__forceinline sProto* GetProto(long pid) {
+	sProto* proto = nullptr;
+	return GetProto(pid, proto) ? proto : nullptr;
+}
 
 // wrapper for skill_get_tags with bounds checking
 void SkillGetTags(long* result, long num);

sfall/Inventory.cpp

@@ -315,7 +315,7 @@ static void __cdecl DisplaySizeStats(TGameObj* critter, const char* &message, DW
 	sizeMax = limitMax;
 	size = sfgame_item_total_size(critter);
 
-	const char* msg = MsgSearch(ptr_inventry_message_file, 35);
+	const char* msg = MessageSearch(ptr_inventry_message_file, 35);
 	message = (msg != nullptr) ? msg : "";
 
 	strcpy(InvenFmt, InvenFmt1);
@@ -343,13 +343,13 @@ static char SizeMsgBuf[32];
 static const char* __stdcall SizeInfoMessage(TGameObj* item) {
 	int size = fo_item_size(item);
 	if (size == 1) {
-		const char* message = MsgSearch(ptr_proto_main_msg_file, 543);
+		const char* message = MessageSearch(ptr_proto_main_msg_file, 543);
 		if (message == nullptr)
 			strcpy(SizeMsgBuf, "It occupies 1 unit.");
 		else
 			strncpy_s(SizeMsgBuf, message, _TRUNCATE);
 	} else {
-		const char* message = MsgSearch(ptr_proto_main_msg_file, 542);
+		const char* message = MessageSearch(ptr_proto_main_msg_file, 542);
 		if (message == nullptr)
 			sprintf(SizeMsgBuf, "It occupies %d units.", size);
 		else