Deprecated Features

[meko 170]

List of deprecated script commands and Hercules features

(2017)

• misceffect()
• specialeffect2()
• pow()
• useatcmd()

 

v2018.06.03

• pcblockmove()

 

v2019.03.10

• UDT_MAPIDXY and UDT_WALKTOXY constant

 

v2019.04.07

• petstat()

 

v2019.05.05

• debugmes()

 

v2019.11.17

• getguildname()
• getguildmaster()
• getguildmasterid()

 

 

Future deprecations:

⚠️ Please avoid using those commands in new scripts

• menu()

[meko 170]

As of June 3rd, the specialeffect() command has been upgraded and it now allows to use effects on any kind of unit (player, npc, mob, homunculus, ...) and to show it to any player. This allowed us to deprecate specialeffect2() and misceffect() so now there is a single command for effects instead of 3 different ones, making things simpler for everyone. You can still use specialeffect2() and misceffect() but they will trigger a warning every time, since they will be removed in the future.

 

Here's how the updated specialeffect() command works:

 

specialeffect(effect number{, send target{, unit id{, account id ]}})

 

effect number is the effect to use.
see effect_list.txt for a list of all effects

 

send target is to whom the effect should be sent. The most common values are:

AREA will show the effect to every player in the area
SELF will show the effect to one player only

see constants.md for a list of possible send targets

 

unit id is the unit on which the effect should be centered
it can be a mob id, an account id, a npc id or the id of any other kind of unit

 

account id is the player to which the effect should be sent if SELF was specified as send target

 

To migrate from specialeffect2 to specialeffect:
 

specialeffect2(effect) ➜ specialeffect(effect, AREA, playerattached())

specialeffect2(effect, target, "player name") ➜ specialeffect(effect, target, getcharid(CHAR_ID_ACCOUNT, "player name"))

 

To migrate from misceffect to specialeffect:

Because the behaviour of this command varies depending on if the npc has a sprite or not, what you want is either one of the two:

misceffect(effect) ➜ specialeffect(effect)

misceffect(effect) ➜ specialeffect(effect, AREA, playerattached())

[meko 170]

As of June 3rd, the pow() command has been superseded by the exponentiation operator (**). You can still use pow() but it will trigger a warning every time, as this command will be removed in the future.

 

The exponentiation operator has higher precedence than any other operator.

This means (a * b ** c) is equivalent to (a * (b ** c)) and not ((a * b) ** c)

 

 

 

Here's how to migrate your scripts:

 

pow(a, b) ➜ (a ** b)

 

 

In combination with other operators:

 

pow(a * b, c) ➜ ((a * b) ** c)

pow(a, b * c) ➜ (a ** (b * c))

 

 

 

To automatically convert your scripts:

# from the Hercules root folder:
find npc db -type f -exec sed -i -r 's/pow\((.+),[ ]*(.+)\)/((\1) ** (\2))/g' {} +

 

 

If you are using vanilla Hercules then all your scripts should already be converted.

See also http://herc.ws/board/topic/14848-deprecation-specialeffect2-misceffect/

[meko 170]

As of September 18 2017, the useatcmd() command has been deprecated.

If you were using useatcmd() for built-in @commands you can simply replace it with atcommand():

useatcmd("@command") ➜ atcommand("@command")

 

 

If you were using useatcmd() for custom @commands (registered with bindatcmd()) you can use doevent() instead:

useatcmd("@custom") ➜ doevent("MyNPC::OnUseCommand");

MyNPC is the name of the NPC in which you used bindatcmd()
OnUseCommand is the event you registered with bindatcmd()

 

Edge cases:
useatcmd(), unlike atcommand(), uses the group id of the attached player rather than running with admin privileges. If you need to check whether or not a player should be able to use a command, use can_use_command()

if (can_use_command("@foobar")) {
	atcommand("@foobar");
} else {
	dispbottom("You cannot use this command!");
}

 

[AnnieRuru 957]

Related commit : https://github.com/HerculesWS/Hercules/pull/842

if you have event scripts that uses *pcblockmove, its time to convert into *setpcblock

 

Example : (old)

pcblockmove(getcharid(CHAR_ID_ACCOUNT), true);

now should be

setpcblock(PCBLOCK_MOVE, true);

 

the new one is more flexible and can limit other actions too

[AnnieRuru 957]

Related commit: https://github.com/HerculesWS/Hercules/pull/2391

this is part of *setunitdata script command clean-up
the UDT_MAPIDXY and UDT_WALKTOXY constant has been deprecated so this script command only dealing with 1 INTEGER value
now it has been standardize, all (int) has been removed from the documentation

 

Example 1 : setunitdata UDT_MAPIDXY (old)

	.@mobgid = monster("this", -1,-1, "--ja--", PORING, 1);
	setunitdata(.@mobgid, UDT_MAPIDXY, "guild_vs2", 50,50);

now should be

	.@mobgid = monster("this", -1,-1, "--ja--", PORING, 1);
	unitwarp(.@mobgid, "guild_vs2", 50,50);

 

---

Example 2 : getunitdata UDT_MAPIDXY (old)

	.@mobgid = monster("this", -1,-1, "--ja--", PORING, 1);
	getunitdata(.@mobgid, UDT_MAPIDXY, .@pos);
	dispbottom(sprintf("%d %d %d", .@pos[0], .@pos[1], .@pos[2]));
	// apparently we don't have *mapid2name script command ... doesn't matter anymore

now should be

	.@mobgid = monster("this", -1,-1, "--ja--", PORING, 1);
	getmapxy(.@map$, .@x, .@y, UNITTYPE_MOB, .@mobgid);
	dispbottom(sprintf("%s %d %d", .@map$, .@x, .@y));

 

---

Example 3 : setunitdata UDT_WALKTOXY (old)

	.@mobgid = monster("this", -1,-1, "--ja--", PORING, 1);
	setunitdata(.@mobgid, UDT_WALKTOXY, 158,185);

now should be

	.@mobgid = monster("this", -1,-1, "--ja--", PORING, 1);
	unitwalk(.@mobgid, 158, 185);

 

[Ridley 295]

Related commit:
https://github.com/HerculesWS/Hercules/pull/2566 and present in https://github.com/HerculesWS/Hercules/commits/stable

getguildinfo()

getguildname()

getguildmaster()

getguildmasterid()

Script Conversion:

find npc db -type f -exec sed -i -e "s/getguildname(/getguildinfo(GUILDINFO_NAME, /g" \
-e "s/getguildmaster(/getguildinfo(GUILDINFO_MASTER_NAME, /g" \
-e "s/getguildmasterid(/getguildinfo(GUILDINFO_MASTER_CID, /g" {} +

Format and Values:

*getguildinfo(<info type>{, <guild id>})
*getguildinfo(<info type>{, "<guild name>"})
  
Valid <info type> are:
	GUILDINFO_NAME          - guild name
	GUILDINFO_ID            - guild id
	GUILDINFO_LEVEL         - current level
	GUILDINFO_EXP           - current exp
	GUILDINFO_NEXT_EXP      - exp required to reach the next level
	GUILDINFO_SKILL_POINTS  - available skill points
	GUILDINFO_ONLINE        - number of online members
	GUILDINFO_AV_LEVEL      - average member level
	GUILDINFO_MAX_MEMBERS   - guild capacity
	GUILDINFO_MASTER_NAME   - name of the guild master
	GUILDINFO_MASTER_CID    - char id of the guild master

Example:

1Old: 

getguildmaster(getcharid(CHAR_ID_GUILD))

1New:

getguildinfo(GUILDINFO_MASTER_NAME, getcharid(CHAR_ID_GUILD))

2Old:

getguildname(getcharid(CHAR_ID_GUILD))

2New:

getguildinfo(GUILDINFO_NAME, getcharid(CHAR_ID_GUILD))

 

[Ridley 295]

Related commit:
https://github.com/HerculesWS/Hercules/pull/2440

 

consolemes()

debugmes()

 

 

 

Format and Values:

consolemes("<type>", "<format string>"{,<param>{, ...}})
  List of available <type> are:
	CONSOLEMES_DEBUG   = 0
	CONSOLEMES_ERROR   = 1
	CONSOLEMES_WARNING = 2
	CONSOLEMES_INFO    = 3
	CONSOLEMES_STATUS  = 4
	CONSOLEMES_NOTICE  = 5

Example:

Old: 

debugmes("Please check your special warp menu settings on the Warpra.");

New:

consolemes(CONSOLEMES_WARNING, "Please check your special warp menu settings on the Warpra.");

consolemes(CONSOLEMES_DEBUG, "%s has clicked me!", strcharinfo(PC_NAME));

consolemes(CONSOLEMES_DEBUG, "\033[0;32mHello World"); // supports ANSI escape sequences

 

[Ridley 295]

Related commit:

https://github.com/HerculesWS/Hercules/pull/2398

This command will return the currently active pet information of the invoking character.

getpetinfo(<type>)

petstat(<flag>)

 

 

 

Types:

PETINFO_ID            - Pet Database ID, stored in `pet` table to distinguish from other pets.
PETINFO_CLASS         - Pet class ID. (Id field)
PETINFO_NAME          - Pet Name, return "null" if there's no active pet.
PETINFO_INTIMACY      - Pet Intimacy level. 1000 is full loyalty.
PETINFO_HUNGRY        - Pet hungry level. 100 is completely full.
PETINFO_RENAME        - Pet rename flag. 0 means this pet has not been named yet.
PETINFO_GID           - Pet Game ID
PETINFO_EGGITEM       - Pet EggItem
PETINFO_FOODITEM      - Pet FoodItem
PETINFO_ACCESSORYITEM - Pet AccessoryItem
PETINFO_ACCESSORYFLAG - return 1 if the pet currently equipping accessory, return 0 otherwise.
PETINFO_EVO_EGGID     - Pet Evolve EggID
PETINFO_AUTOFEED      - Pet AutoFeed flag.