QUESTS AND QUEST MEMOS (Quest / Memo)
26 functionsHaveMemoGLOBAL🟢 high
The most frequent check in the whole group: does the character cCreature have an active memo of the given quest nQuestId (identifier from [quest_pch]). The function belongs to the global object (gg). Returns one (@TRUE) if the quest is taken, and zero if not.
Signature
HaveMemo( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — whom we check.
nQuestId (int) — the quest.
values — from the [quest_pch] dictionaryExample
if ( HaveMemo( talker, @the_wishing_potion ) == 0 ) {Usage example
if ( HaveMemo( target, @relics_of_the_old_empire ) == 1 ) {
random1_list.SetInfo( 0, target );
}GetMemoStateGLOBAL🟢 high
Reads the numeric state of a quest — what SetMemoState wrote — for character cCreature and quest nQuestId (from [quest_pch]). The function belongs to the global object (gg). If there is no memo, it usually returns zero.
Signature
GetMemoState( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — the player.
nQuestId (int) — the quest.
values — from the [quest_pch] dictionaryExample
i0 = GetMemoState( talker, @supplier_of_reagents );Usage example
if ( HaveMemo( talker, @succession_to_the_legend_shillien_saint ) == 1 && talker.occupation == @shillien_elder && GetMemoState( talker, @succession_to_the_legend_shillien_saint ) == 14 && OwnItemCount( talker, @q_resonance_amulet6_29 ) == 0 && myself.i_quest0 == 1 && myself.sm.param2 == talker.dbid ) {
ShowPage( talker, "abyss_maiden_elcardia_q0098_0110.htm" );
}GetMemoStateExGLOBAL🟢 high
Reads the value from additional slot nSlot of the state of quest nQuestId (from [quest_pch]) for character cCreature — the counterpart of SetMemoStateEx. The function belongs to the global object (gg); the slot index is in the range 0…3.
Signature
GetMemoStateEx( CSharedCreatureData cCreature, int nQuestId, int nSlot )Parameters
cCreature (CSharedCreatureData) — the player.
nQuestId (int) — the quest.
values — from the [quest_pch] dictionary
nSlot (int) — slot index 0…3.Example
i2 = GetMemoStateEx( talker, @gourd_event, 1 );Usage example
i0 = GetMemoStateEx( talker, @seductive_whispers, 1 );
if ( i0 < 0 ) { i0 = 0; }GetDailyQuestFlagGLOBAL🟢 high
Checks the completion mark of the daily quest nQuestId (from [quest_pch]) for character cCreature. The function belongs to the global object (gg). The flag is automatically reset once a day early in the morning, after which the quest becomes available again.
Signature
GetDailyQuestFlag( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — the player.
nQuestId (int) — the daily quest.
values — from the [quest_pch] dictionaryExample
if (GetDailyQuestFlag(talker, @daily_queen_ant) == 1)Usage example
if (HaveMemo(talker, @proof_of_valrakas_hunting) == @FALSE && GetDailyQuestFlag(talker, @proof_of_valrakas_hunting) == @TRUE && OwnItemCount(talker, @q_floating_stone) >= 1 && talker.level >= 84) {
ShowPage(talker, "watcher_valakas_klein_q0907_05.htm");
}SetDailyQuestFlagGLOBAL🟢 high
Marks that character cCreature has completed the daily quest nQuestId (from [quest_pch]). The counterpart of GetDailyQuestFlag; the flag is automatically reset once a day early in the morning, after which the quest becomes available again.
Signature
SetDailyQuestFlag( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — the creature that gets the daily quest completion flag
nQuestId (int) — identifier of the daily quest from the [quest_pch] dictionary
values — from the [quest_pch] dictionaryExample
SetDailyQuestFlag(talker, @promise);Usage example
else {
SetDailyQuestFlag( talker, @daily_fall_of_the_dragon );
CastBuffForQuestReward( talker, CHECK_SKILL );
ShowPage( talker, "nevit_s_herald003.htm" );
}SetMemoNPC🟢 high
Creates a quest memo record on the character (argument cCreature, usually talker) — effectively grants the quest and registers it as active. The second argument nQuestId is the quest identifier from the [quest_pch] dictionary. The quest state is then managed by SetMemoState/GetMemoState; the purpose of the return value is unconfirmed.
Signature
SetMemo( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — who receives the quest (usually talker).
nQuestId (int) — quest identifier (@...).
values — from the [quest_pch] dictionaryExample
SetMemo( c1, @blood_offering );Usage example
if ( HaveMemo( talker, @gourd_event ) == 0 ) {
SetMemo( talker, @gourd_event );
}RemoveMemoNPC🟢 high
Deletes the quest memo from character cCreature: the quest was completed or abandoned. The second argument nQuestId is a quest from [quest_pch]. After the call, HaveMemo for this quest starts returning zero; the purpose of the return value is unconfirmed.
Signature
RemoveMemo( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — whose quest is removed.
nQuestId (int) — quest.
values — from the [quest_pch] dictionaryExample
RemoveMemo( c1, @blood_offering );Usage example
if ( i2 < 1262221261 ) {
RemoveMemo( talker, @gourd_event );
}GetMemoCountNPC🟢 high
Returns the number of active memos (quests taken simultaneously) on character cCreature. Used as a safeguard against overflow: a new quest is granted only if the player has fewer than the maximum allowed.
Signature
GetMemoCount( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — whose quests are counted.Example
if ( GetMemoCount( talker ) < @MAX_QUEST_NUM ) {Usage example
if ( GetMemoCount( talker ) >= 25 ) {
ShowPage( talker, "fullquest.htm" );
return;
}SetMemoStateNPC🟢 high
Writes the numeric state (stage) of a quest: for character cCreature and quest nQuestId (from [quest_pch]) it sets the value nState. The semantics of the number are entirely defined by the quest script itself — in some places it is 1, 2, 3, in others tens or even tens of thousands; the value can be assigned directly or incremented after reading the previous one.
Signature
SetMemoState( CSharedCreatureData cCreature, int nQuestId, int nState )Parameters
cCreature (CSharedCreatureData) — player.
nQuestId (int) — quest.
values — from the [quest_pch] dictionary
nState (int) — new state/stage.Example
SetMemoState( c1, @testimony_of_trust, 3 );Usage example
if ( reply == 71 && HaveMemo( talker, @in_the_name_of_evil_part2 ) == 1 && GetMemoState( talker, @in_the_name_of_evil_part2 ) == 407 && GetOneTimeQuestFlag( talker, @in_the_name_of_evil_part2 ) == 0 ) {
SetMemoState( talker, @in_the_name_of_evil_part2, 408 );
ShowPage( talker, "asama_q0126_26.htm" );
}SetMemoStateExNPC🟢 high
Writes the value nState into the additional slot nSlot of the state of quest nQuestId (from [quest_pch]) for character cCreature. Unlike SetMemoState, which has a single main state, it provides several independent numeric cells addressed by slot number (indices 0…3 — four cells per quest).
Signature
SetMemoStateEx( CSharedCreatureData cCreature, int nQuestId, int nSlot, int nState )Parameters
cCreature (CSharedCreatureData) — player.
nQuestId (int) — quest.
values — from the [quest_pch] dictionary
nSlot (int) — slot index 0…3 (4 cells per quest: 0→nState, 1→nState2, 2→nState3, 3→nState4). Confirmed by the source code.
nState (int) — value for the slot.Example
SetMemoStateEx( talker, @four_goblets, 2, i0 );Usage example
if ( ( i0 % 10 ) == 0 ) {
SetMemoStateEx( talker, @resurrection_of_old_manager, 1, ( i0 + 1 ) );
}SetFlagJournalNPC🟢 high
Changes the quest step visible to the player in the quest window: for character cCreature and quest nQuestId (from [quest_pch]) it sets the displayed step number nStep. This is the quest's "storefront", whereas SetMemoState is its internal machinery; the two calls often stand side by side and operate on the same number, but sometimes the internal state and the displayed step deliberately diverge.
Signature
SetFlagJournal( CSharedCreatureData cCreature, int nQuestId, int nStep )Parameters
cCreature (CSharedCreatureData) — player.
nQuestId (int) — quest.
values — from the [quest_pch] dictionary
nStep (int) — step number to display.Example
SetFlagJournal( c1, @testimony_of_life, 5 );Usage example
if ( OwnItemCount( c1, @ol_mahum_runestone ) >= 1 && OwnItemCount( c1, @turek_runestone ) >= 1 && OwnItemCount( c1, @turak_bugbear_runestone ) >= 1 ) {
SetFlagJournal( c1, @trial_of_the_seeker, 5 );
ShowQuestMark( c1, @trial_of_the_seeker );
}ShowQuestMarkNPC🟢 high
Shows player cCreature a quest indicator — the familiar quest-received mark effect for a specific quest nQuestId (from [quest_pch]). Usually called right after granting the memo.
Signature
ShowQuestMark( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — player.
nQuestId (int) — quest.
values — from the [quest_pch] dictionaryExample
ShowQuestMark( c1, @testimony_of_life );ShowQuestionMarkNPC🟢 high
Shows player cCreature a quest mark above the head. The second argument nQuestId is a quest identifier from [quest_pch]: the mark shown is that of this specific quest. In scripts it is written as a raw number (a value from [quest_pch]) rather than an @-name, so at first it looks like an abstract "code"; verification confirmed these numbers match quest IDs (small 1…32 — the classic range, large 10021…10650 — the extended and custom range).
Related event: a click on the "?" arrives as the QUESTION_MARK_CLICKED(talker, question_id) event (see NASC_HANDLERS).
Signature
ShowQuestionMark( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — player.
nQuestId (int) — quest whose mark to show.
values — from the [quest_pch] dictionaryExample
ShowQuestionMark(talker, 26);Usage example
if ( i3 == 3 ) {
ShowQuestionMark( talker, 5 );
SoundEffect( talker, "ItemSound.quest_tutorial" );
}ShowQuestionMark2NPC🟢 high
A delayed variant of ShowQuestionMark: shows the quest mark not immediately, but after a given delay. Per the decompiled code, the engine sets a timer (CShowQuestionMarkTimer) and, when it fires, shows the mark of quest nQuestId above the creature's head. The first numeric argument is a quest ID from [quest_pch] (as in ShowQuestionMark), the second is the delay in SECONDS (converted internally to ms: nDelay·1000). No live calls found in the scripts.
Related event: a click on the "?" arrives as the QUESTION_MARK_CLICKED(talker, question_id) event (see NASC_HANDLERS).
Signature
ShowQuestionMark2( CSharedCreatureData cCreature, int nQuestId, int nDelay )Parameters
cCreature (CSharedCreatureData) — creature to which the question mark is shown
nQuestId (int) — quest identifier from the [quest_pch] dictionary
nDelay (int) — delay in seconds before showing the mark (the engine sets a timer for nDelay·1000 ms). Confirmed by the decompiled code.
Example (illustrative):
ShowQuestionMark2( talker, nQuestId, nDelay );ShowQuestPageNPC🟢 high
Shows player cCreature a dialog html page (argument sHtmlName — name of the html file) bound to a specific quest nQuestId (from [quest_pch]). Essentially this is ShowPage, but with the quest specified, so the window opens in the correct quest context.
Signature
ShowQuestPage( CSharedCreatureData cCreature, string sHtmlName, int nQuestId )Parameters
cCreature (CSharedCreatureData) — player.
sHtmlName (string) — html file name.
nQuestId (int) — quest.
values — from the [quest_pch] dictionaryExample
ShowQuestPage(talker, "arujien_q0002_00.htm", @what_women_want);Usage example
if ( GetMemoCount( talker ) < @MAX_QUEST_NUM ) {
ShowQuestPage( talker, "blacksmith_wilbert_q0663_01.htm", @seductive_whispers );
} else {
ShowPage( talker, "fullquest.htm" );
}ShowQuestFHTMLNPC🟢 high
Does the same as ShowQuestPage, but the page is not taken from a ready-made file — it is assembled on the fly as a CFHTML object (argument fhtml). The third argument nQuestId is a quest from [quest_pch]. No direct calls found in the collection.
Signature
ShowQuestFHTML( CSharedCreatureData cCreature, CFHTML fhtml, int nQuestId )Parameters
cCreature (CSharedCreatureData) — player.
fhtml (CFHTML) — dynamic html object.
nQuestId (int) — quest.
values — from the [quest_pch] dictionaryExample
ShowQuestFHTML( talker, fhtml0, @black_swan );ShowQuestInfoListNPC🟢 high
Opens for player cCreature the quest list or quest window of this NPC — a listing of available quests. No direct calls found in the collection.
Signature
ShowQuestInfoList( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — player.Example
ShowQuestInfoList(talker);SetCurrentQuestIDNPC🟢 high
Declares which quest nQuestId (from [quest_pch]) is considered current in this handling: after the call, subsequent quest actions of the NPC apply to that quest. Usually placed at the very start of processing the player's dialog choice; the purpose of the return value is unconfirmed.
Signature
SetCurrentQuestID( int nQuestId )Parameters
nQuestId (int) — quest to make "current".
values — from the [quest_pch] dictionaryExample
SetCurrentQuestID( @q_mimirs_elixir );Usage example
if ( _from_choice == 0 || ( HaveMemo( talker, @find_sir_windawood ) == 0 && GetOneTimeQuestFlag( talker, @find_sir_windawood ) == 1 ) ) {
SetCurrentQuestID( @find_sir_windawood );
ShowPage( talker, "finishedquest.htm" );
}CheckAndSetTransactMemoNPC🟢 high
An atomic transaction "lock" for character cCreature: in a single action it checks whether an operation is already in progress for this player and immediately sets the busy flag. Returns @TRUE if it is safe to proceed (the lock was successfully acquired), and @FALSE if a grant is already being performed — in that case the script aborts and the reward is not given out twice. Its counterpart ResetTransactMemo releases the lock (commits the transaction) after the operation completes successfully.
Signature
CheckAndSetTransactMemo( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — player.Example
if ( CheckAndSetTransactMemo( talker ) == @FALSE ) { return; }Usage example
if ( CheckAndSetTransactMemo( talker ) ) {
GiveItem1( talker, @q_adventure_coupon1, 1 );
SetOneTimeQuestFlag( talker, @207, 1 );
ShowPage( talker, fnCoupon1Ok );
}TriggerCompleteQuestNPC🟢 high
Queues an atomic server task that asynchronously marks quest nQuestId (from [quest_pch]) as completed for character cCreature. Unlike the manual combination of RemoveMemo plus SetOneTimeQuestFlag, it is executed by the engine as a single transaction — without races, updating all server-side bookkeeping of quest completion.
Signature
TriggerCompleteQuest( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — player.
nQuestId (int) — quest.Example
TriggerCompleteQuest(target, @tiat);GetAccountQuestCompleteCountNPC🟢 high
Reads the completion counter of quest nQuestId (from [quest_pch]) for the game account of character c, rather than for the individual character. Used for "once per account" limits — for a reward or quest that cannot be completed again by another character of the same account.
Signature
GetAccountQuestCompleteCount( CSharedCreatureData c, int nQuestId )Parameters
c (CSharedCreatureData) — player (their account is used).
nQuestId (int) — quest.
Example (illustrative):
GetAccountQuestCompleteCount( talker, nQuestId );IncrementAccountQuestCompleteCountNPC🟢 high
Increments the completion counter of quest nQuestId (from [quest_pch]) for the game account of character c. Counterpart of GetAccountQuestCompleteCount; serves for "once per account" limits.
Signature
IncrementAccountQuestCompleteCount( CSharedCreatureData c, int nQuestId )Parameters
c (CSharedCreatureData) — creature whose game account gets the quest completion counter incremented
nQuestId (int) — quest identifier from the [quest_pch] dictionary
Example (illustrative):
IncrementAccountQuestCompleteCount( talker, nQuestId );GetOneTimeQuestFlagNPC🟢 high
Reads the flag of a one-time quest or event for character cCreature — a mark that they have already done something unrepeatable. The second argument nFlagId is resolved through [quest_pch] (in scripts it also appears as a number). Returns one if already done, zero otherwise; often placed right after a HaveMemo check, to distinguish "quest not taken yet" from "quest already completed at some point".
Signature
GetOneTimeQuestFlag( CSharedCreatureData cCreature, int nFlagId )Parameters
cCreature (CSharedCreatureData) — player.
nFlagId (int) — identifier of the one-time quest/event.
values — from the [quest_pch] dictionaryExample
if ( GetOneTimeQuestFlag( talker, @in_the_name_of_evil_part1 ) == 0 ) {Usage example
if ( HaveMemo( talker, @in_the_name_of_evil_part2 ) == 0 && talker.level >= 77 && GetOneTimeQuestFlag( talker, @in_the_name_of_evil_part1 ) != 0 && GetOneTimeQuestFlag( talker, @in_the_name_of_evil_part2 ) == 0 ) {
ShowPage( talker, "asama_q0126_05.htm" );
}SetOneTimeQuestFlagNPC🟢 high
Sets or clears the flag of a one-time quest/event for character cCreature: argument nFlagId (from [quest_pch]) specifies the event, and nValue equal to 1 marks it as done while 0 removes the mark. Counterpart of GetOneTimeQuestFlag.
Signature
SetOneTimeQuestFlag( CSharedCreatureData cCreature, int nFlagId, int nValue )Parameters
cCreature (CSharedCreatureData) — player.
nFlagId (int) — identifier of the one-time quest/event.
values — from the [quest_pch] dictionary
nValue (int) — 1 — done, 0 — reset.Example
SetOneTimeQuestFlag( talker, @blood_fiend, 1 );Usage example
if ( i1 > 0 ) {
SetOneTimeQuestFlag( c0, i1, 0 );
}CastBuffForQuestReward2NPC🟢 high
Applies a buff to character cCreature (often myself.sm) as a quest reward or effect, specifying the skill by its name-identifier nSkillNameId from the [skill_pch] dictionary. This is a "service" cast: it does not depend on the desire queue or combat restrictions, so it fires guaranteed.
Signature
CastBuffForQuestReward2( CSharedCreatureData cCreature, int skillname_id )Parameters
cCreature (CSharedCreatureData) — buff target (often myself.sm).
skillname_id (int) — skill/buff (@s_...).Example
CastBuffForQuestReward2( talker, @s_wind_walk2);Usage example
if ( i5 <= 0 && Rand( 100 ) < LongRangeGuardRate ) {
CastBuffForQuestReward2( myself.sm, @s_npc_ultimate_defence3 );
}CastBuffForQuestRewardNPC🟢 high
An older variant of CastBuffForQuestReward2 — applies a reward buff to character cCreature. The second argument is a buff skill from the [skill_pch] dictionary (in calls @s_npc_haste1, @s_npc_ultimate_defence3 or a local variable Buff holding such an id).
Signature
CastBuffForQuestReward( CSharedCreatureData cCreature, int nSkillNameId )Parameters
cCreature (CSharedCreatureData) — buff target.
nSkillNameId (int) — skill/buff (@s_...).
values — from the [skill_pch] dictionaryExample
CastBuffForQuestReward( talker, @s_npc_haste1 );Usage example
if ( DistFromMe( c0 ) <= 75 ) {
CastBuffForQuestReward( c0, Buff );
}ITEMS (Item)
18 functionsOwnItemCountGLOBAL🟢 high
Returns the total number of items of class nItemClassId (from [item_pch]) that creature c (usually talker) has. Enchant level and augmentation are ignored — all instances are counted. The basic way to check for a quest item or find out the amount of adena.
Signature
OwnItemCount( CSharedCreatureData c, int nItemClassId )Parameters
c (CSharedCreatureData) — whose items we count (usually talker).
nItemClassId (int) — item class (@adena, @official_letter…).
values — from the [item_pch] dictionaryExample
i1 = OwnItemCount( talker, @q_watching_eyes );Usage example
if ( HaveMemo( talker, @succession_to_the_legend_shillien_saint ) == 1 && talker.occupation == @shillien_elder && GetMemoState( talker, @succession_to_the_legend_shillien_saint ) == 14 && OwnItemCount( talker, @q_resonance_amulet6_29 ) == 0 && myself.i_quest0 == 1 && myself.sm.param2 == talker.dbid ) {
ShowPage( talker, "abyss_maiden_elcardia_q0098_0110.htm" );
}OwnItemCount2GLOBAL🟢 high
Same as OwnItemCount, but with an extra flag bFindAugment: for creature c it counts the number of items of class nItemClassId (from [item_pch]), and with bFindAugment = 1 the count takes augmentation into account, while with 0 the function behaves like a regular OwnItemCount.
Signature
OwnItemCount2( CSharedCreatureData c, int nItemClassId, int bFindAugment )Parameters
c (CSharedCreatureData) — whose items we count.
nItemClassId (int) — item class.
bFindAugment (int) — take augmentation into account (0/1).
Example (illustrative):
OwnItemCount2( talker, nItemClassId, bFindAugment );OwnItemCountEx2GLOBAL🟢 high
The most complete counter: for creature c it counts items of class nItemClassId (from [item_pch]), filtering simultaneously by enchant level nEnchantLevel and by augmentation (bFindAugment, 0/1). Combines the capabilities of OwnItemCountEx and OwnItemCount2.
Signature
OwnItemCountEx2( CSharedCreatureData c, int nItemClassId, int nEnchantLevel, int bFindAugment )Parameters
c (CSharedCreatureData) — whose items we count.
nItemClassId (int) — item class.
nEnchantLevel (int) — required enchant level.
bFindAugment (int) — take augmentation into account (0/1).
Example (illustrative):
OwnItemCountEx2( talker, nItemClassId, nEnchantLevel, bFindAugment );OwnItemEnchantCountGLOBAL🟢 high
Returns the enchant level of the item of class nItemClassId (from [item_pch]) owned by creature c — NOT the number of pieces (the name is misleading). If the item is absent, returns 0. If the player has several matching instances with different enchant levels, the function returns the enchant level of the LAST one found while traversing the inventory (not the maximum and not the sum) — do not rely on this; the check is intended for a single item.
Signature
OwnItemEnchantCount( CSharedCreatureData cCreature, int nItemClassId )Parameters
cCreature (CSharedCreatureData) — whose inventory we look at.
nItemClassId (int) — item class.
values — from the [item_pch] dictionaryExample
i0 = OwnItemEnchantCount(talker, @ev_fake_dualblunt);
i0 = OwnItemEnchantCount( talker, talker.equiped_weapon_class_id );
i0 = OwnItemEnchantCount( talker, yogy_staff );GetItemCollectableGLOBAL🟢 high
Returns 1 if creature cCreature has spoil items ready to collect, otherwise 0. Essentially this is a check of whether the loot on a spoiled mob can be swept (collected) right now.
Signature
GetItemCollectable( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature being checked (a mob with spoil).Example
if (GetItemCollectable(myself.sm) == @TRUE)Usage example
if ( GetItemCollectable( myself.sm ) == 1 ) {
if ( Rand( 5 ) < 2 ) {
CreateOnePrivateEx( @dragon_knight_5, "dragon_knight_5", 0, 0, FloatToInt( myself.sm.x ), FloatToInt( myself.sm.y ), FloatToInt( myself.sm.z ), 0, 1000, GetIndexFromCreature( myself.top_desire_target ), 0 );
}
} else
if ( Rand( 5 ) < 1 ) {
CreateOnePrivateEx( @dragon_knight_5, "dragon_knight_5", 0, 0, FloatToInt( myself.sm.x ), FloatToInt( myself.sm.y ), FloatToInt( myself.sm.z ), 0, 1000, GetIndexFromCreature( myself.top_desire_target ), 0 );
}OwnItemCountExNPC🟢 high
Counts the number of items of class nItemClassId (from [item_pch]) owned by creature c, but only with the specific enchant level nEnchantLevel. Handy when the enchanted version of the item is what matters. Returns the number of matching instances.
Signature
OwnItemCountEx( CSharedCreatureData cCreature, int nItemClassId, int nEnchantLevel )Parameters
cCreature (CSharedCreatureData) — whose items are counted.
nItemClassId (int) — item class.
values — from the [item_pch] dictionary
nEnchantLevel (int) — required enchant level.Example
if (IsInCategory(@third_class_group, talker.occupation) == 1 && OwnItemCountEx(talker, 5708, GetSSQRoundNumber()) > 0) {Usage example
if ( IsInCategory( @third_class_group, talker.occupation ) == 1 && OwnItemCountEx( talker, @the_lord_of_manor_s_agreement, GetSSQRoundNumber( ) ) > 0 ) {
ShowPage( talker, szName + "_" + QUEST_ID + "_07.htm" );
}GiveItem1NPC🟢 high
Gives creature c (usually talker or target) nCount pieces of item nItemClassId (from [item_pch]) without enchant. The most common way to hand over a quest item or reward. If nCount is computed and comes out as 0, the item is effectively not given.
Signature
GiveItem1( CSharedCreatureData cCreature, int nItemClassId, int64 nCount )Parameters
cCreature (CSharedCreatureData) — who receives it (usually talker/target).
nItemClassId (int) — item class.
values — from the [item_pch] dictionary
nCount (int64) — count.Example
GiveItem1( talker, @q_info_urz, 1 );Usage example
if ( i1 == 3 ) {
GiveItem1( c1, @demon_s_gloves_fabric, 1 );
}GiveItemExNPC🟢 high
Like GiveItem1, but gives creature c nCount pieces of item nItemClassId (from [item_pch]) with the specified enchant level nEnchantLevel. Used for reward items with a fixed or random enchant level.
Signature
GiveItemEx( CSharedCreatureData cCreature, int nItemClassId, int nEnchantLevel, int64 nCount )Parameters
cCreature (CSharedCreatureData) — who receives it.
nItemClassId (int) — item class.
values — from the [item_pch] dictionary
nEnchantLevel (int) — enchant level of the given item.
nCount (int64) — count.Example
GiveItemEx( talker, @br_xmas_shirts, 6, 1 );Usage example
if ( OwnItemCount( talker, @br_xmas_wpn_ticket_normal ) > 0 ) {
GiveItemEx( talker, i1, 4 + Rand( 13 ), 1 );
DeleteItem1( talker, @br_xmas_wpn_ticket_normal , 1 );
ShowPage( talker, "br_xmas_wannabe_santa2024.htm" );
} else {
ShowPage( talker, "br_xmas_wannabe_santa2023.htm" );
}GiveEventItemNPC🟢 high
Performs an exchange in a single action: takes from pTarget (usually talker) nReqAmount pieces of item nReqItemId (from [item_pch], e.g. @adena) and in return gives nGiveAmount pieces of item nGiveItemId (also from [item_pch]). The nId argument specifies the event identifier or category, and nTimeLimit is the time limit in hours on the temporary item given out. There is an extended version, GiveEventItem2, that for a single payment gives two different items at once.
Signature
GiveEventItem( CSharedCreatureData pTarget, int nReqItemId, int64 nReqAmount, int nGiveItemId, int64 nGiveAmount, int nId, int nTimeLimit )Parameters
pTarget (CSharedCreatureData) — to whom / from whom (usually talker).
nReqItemId (int) — what to take (the payment, e.g. @adena).
values — from the [item_pch] dictionary
nReqAmount (int64) — how much to take.
nGiveItemId (int) — what to give.
values — from the [item_pch] dictionary
nGiveAmount (int64) — how much to give.
nId (int) — event id/category.
nTimeLimit (int) — lifetime of the given item (hours).Example
GiveEventItem( talker, @adena, 500, search_scroll, 1, 0, 12 );Usage example
if ( reply == 1 ) {
GiveEventItem( talker, @adena, 1, event_present_skill, 1, 0, 20 );
}DeleteItem1NPC🟢 high
Deletes (confiscates) from creature c nCount pieces of item nItemClassId (from [item_pch]). A common trick is to take all instances by passing OwnItemCount of the same item as the count. Used when completing quests (to collect quest items) and for payments (to deduct adena).
Signature
DeleteItem1( CSharedCreatureData cCreature, int nItemClassId, int64 nCount )Parameters
cCreature (CSharedCreatureData) — from whom to take.
nItemClassId (int) — item class.
values — from the [item_pch] dictionary
nCount (int64) — how many to take.Example
DeleteItem1( talker, @lunargent, 1 );Usage example
if ( OwnItemCount( talker, @adena ) >= GetCookie( talker, "AgitDecoFee" ) ) {
DeleteItem1( talker, @adena, GetCookie( talker, "AgitDecoFee" ) );
ShowPage( talker, fnAfterSetDeco );
} else {
ShowPage( talker, fnNotEnoughAdena );
}DeleteItemExNPC🟢 high
Deletes from creature c nCount pieces of item nItemClassId (from [item_pch]) with the specific enchant level nEnchantLevel — targeted removal of the enchanted version, counterpart of OwnItemCountEx. The argument order was inferred by analogy with GiveItemEx and OwnItemCountEx.
Signature
DeleteItemEx( CSharedCreatureData cCreature, int nItemClassId, int nEnchantLevel, int64 nCount )Parameters
cCreature (CSharedCreatureData) — from whom to take.
nItemClassId (int) — item class.
values — from the [item_pch] dictionary
nEnchantLevel (int) — enchant level.
nCount (int64) — how many to take.
Example (illustrative):
DeleteItemEx( talker, nItemClassId, nEnchantLevel, nCount );DropItem1NPC🟢 high
Drops item nItemClassId (from [item_pch]) in quantity nCount on the ground near the NPC so that creature c — the drop owner — can pick it up. Unlike GiveItem1, which puts the thing directly into the inventory, here the item appears on the ground. Often used by bosses and summons to hand a reward to the summoner (myself.sm).
Signature
DropItem1( CSharedCreatureData cCreature, int nItemClassId, int64 nCount )Parameters
cCreature (CSharedCreatureData) — drop owner (who can pick it up).
nItemClassId (int) — item class.
values — from the [item_pch] dictionary
nCount (int64) — count.Example
DropItem1(myself.sm, @key_of_controller, 1);Usage example
if (Rand(100) < 50) {
DropItem1(myself.sm, 8192, 1);
}DropItem2NPC🟢 high
Like DropItem1, but with an explicit drop-owner id nOwnerId — who is allowed to pick up item nItemClassId (from [item_pch]) in quantity nCount. In raids, the summoner's identifier is passed there so that the drop goes to a specific player rather than to anyone.
Signature
DropItem2( CSharedCreatureData cCreature, int nItemClassId, int64 nCount, int nOwnerId )Parameters
cCreature (CSharedCreatureData) — creature that is the drop context.
nItemClassId (int) — item class.
values — from the [item_pch] dictionary
nCount (int64) — count.
nOwnerId (int) — owner id (who can pick it up).Example
DropItem2( c1, @crystal_a, 4, myself.sm.summoner_id );Usage example
if ( i1 == 0 ) {
DropItem2( myself.sm, @green_soul_crystal_12, 1, myself.sm.summoner_id );
}DropItemsNPC🟢 high
Initiates a drop of items from the NPC's own preconfigured drop lists (defined in the mob's data), rather than a single specific item. The nDropListMask argument is a bit mask selecting which drop sets to use (bits are combined), and pDropOwner specifies who gets the loot.
Signature
DropItems( int nDropListMask, CSharedCreatureData pDropOwner )Parameters
nDropListMask (int) — drop-list bit mask.
pDropOwner (CSharedCreatureData) — drop owner.
Example (illustrative):
DropItems( nDropListMask, talker );GetItemDataNPC🟢 high
Returns the descriptor object (CSharedItemData) of an item of class nItemClassId (from [item_pch]) owned by creature c — for subsequent access to its fields or for passing to other functions. In scripts it is often called right after giving the item, to work with the specific instance.
Signature
GetItemData( CSharedCreatureData cCreature, int nItemClassId )Parameters
cCreature (CSharedCreatureData) — whose item is fetched.
nItemClassId (int) — item class.
values — from the [item_pch] dictionaryExample
GetItemData(talker, @baby_cougar_chime);Usage example
item0 = GetItemData( talker, @manacles_of_redemption );
if ( item0 ) {
DestroyPet( talker, item0.dbid, item0.pet_level );
}UseItemNPC🟢 high
Presumably makes the NPC use the item specified by the single argument. The exact domain of the argument is unconfirmed (inventory index vs. item class), no direct calls found in the collection, so the behavior is described with caution.
Signature
UseItem( int nItem )Parameters
nItem (int) — item the NPC uses (inventory index or item class, domain unconfirmed — 0 calls)
Example (illustrative):
UseItem( nItem );UseCategoryItemNPC🟢 high
Presumably makes the NPC use an item from the category specified by the single argument. Behavior unconfirmed, no calls in the collection.
Signature
UseCategoryItem( int nCategory )Parameters
nCategory (int) — item category from which the NPC uses an item (purpose unconfirmed — 0 calls)
Example (illustrative):
UseCategoryItem( nCategory );EquipItemNPC🟢 high
Makes the NPC equip an item: the single argument nItemClassId is resolved through [item_pch], i.e. it is an item class. No direct calls found in the collection.
Signature
EquipItem( int nItemClassId )Parameters
nItemClassId (int) — class of the item to equip.
values — from the [item_pch] dictionaryExample
EquipItem(@npc_invisi_1hs);Usage example
if (timer_id == 1525007) {
EquipItem(OHS_Weapon1);
}Inventory
4 functionsGetInventoryInfoNPC🟢 high
Returns a numeric inventory metric of creature cCreature — which one is selected by the second argument nInfoType (@IPT_*): @IPT_CURRENT_SLOT_COUNT/@IPT_MAX_SLOT_COUNT (used/maximum slots), @IPT_CURRENT_WEIGHT/@IPT_MAX_CARRY_WEIGHT (current/maximum weight), @IPT_CURRENT_QUEST_SCOUNT/@IPT_MAX_QUEST_SCOUNT (quest slots). The classic use is checking free space and overweight before handing out a reward.
Signature
GetInventoryInfo( CSharedCreatureData cCreature, int Type )Parameters
cCreature (CSharedCreatureData) — creature whose inventory metric is requested
Type (int) — which inventory metric to return
Constants from [manual_pch] are used:
@IPT_CURRENT_SLOT_COUNT (0) — inventory slots currently used
@IPT_MAX_SLOT_COUNT (1) — maximum inventory slots
@IPT_CURRENT_WEIGHT (2) — current carried weight
@IPT_MAX_CARRY_WEIGHT (3) — maximum carry weight
@IPT_CURRENT_QUEST_SCOUNT (4) — quest slots currently used
@IPT_MAX_QUEST_SCOUNT (5) — maximum quest slotsExample
if ( GetInventoryInfo( talker, @IPT_CURRENT_SLOT_COUNT ) >= ( GetInventoryInfo( talker, @IPT_MAX_SLOT_COUNT ) * 0.800000 ) || GetInventoryInfo( talker, @IPT_CURRENT_WEIGHT ) >= ( GetInventoryInfo( talker, @IPT_MAX_CARRY_WEIGHT ) * 0.800000 ) ) {Usage example
if ( GetInventoryInfo( talker, @IPT_CURRENT_SLOT_COUNT ) >= ( GetInventoryInfo( talker, @IPT_MAX_SLOT_COUNT ) * 0.800000 ) || GetInventoryInfo( talker, @IPT_CURRENT_WEIGHT ) >= ( GetInventoryInfo( talker, @IPT_MAX_CARRY_WEIGHT ) * 0.800000 ) ) {
ShowSystemMessage( talker, 1118 );
return;
}UseSoulShotNPC🟢 high
The NPC uses soulshots (a physical attack boost) for nCount charges.
Signature
UseSoulShot( int nCount )Parameters
nCount (int) — the number of soulshot charges used (in calls 10, 20, the variable SoulShot).Example
UseSoulShot( SoulShot );
UseSoulShot( 20 );
UseSoulShot(10);UseSpiritShotNPC🟢 high
The NPC uses spiritshots (a magic attack boost). Per the L2NPC decompile
(CNPC::UseSpiritShot_489FE0) the engine sends the server a packet opcode 113, where the shot type is hardcoded
(=1, spiritshot), and the first argument is the number of charges; two more arguments are named in scripts
SpeedBonus/HealBonus and are passed together with the use.
Signature
UseSpiritShot( int nCount, int nSpeedBonus, int nHealBonus )Parameters
nCount (int) — the number of spiritshot charges used (in calls 20, the variable SpiritShot).
nSpeedBonus (int) — the use-speed bonus (in scripts SpeedBonus/SpiritShotSpeedBonus).
nHealBonus (int) — the restore bonus (in scripts HealBonus/SpiritShotHealBonus).Example
UseSpiritShot( SpiritShot, SpeedBonus, HealBonus );
UseSpiritShot( SpiritShot, SpiritShotSpeedBonus, SpiritShotHealBonus );
UseSpiritShot( 20, SpeedBonus, HealBonus );IsSpoiledNPC🟢 high
Returns whether this NPC is already spoiled (whether spoil is applied): 1 or 0.
Signature
IsSpoiled( )Parameters
(none — the function is called without arguments)Example
if ( Rand( 100 ) < 50 && c1.occupation == @scavenger && IsSpoiled( ) == 1 ) {Usage example
if ( Rand( 100 ) < 50 && c1.occupation == @scavenger && IsSpoiled( ) == 1 ) {
i0 = ( i0 + 1 );
}Skills, abnormals and buffs (Skill / Abnormal)
27 functionsSkill_GetAbnormalLevelGLOBAL🟢 high
Returns the level of the effect that a skill applies. Paired with GetAbnormalLevel(creature, Skill_GetAbnormalType(s)) it lets you determine whether this buff is already on the target at full strength (if the current level is not lower than the skill's level — the buff is present). This is exactly how buffers gray out the buttons of already-granted buffs. The argument nSkillId is a skill from [skill_pch].
Signature
Skill_GetAbnormalLevel( int nSkillId )Parameters
nSkillId (int) — the skill.
values — from the [skill_pch] dictionaryExample
if (GetAbnormalLevel(talker, Skill_GetAbnormalType(buff1)) >= Skill_GetAbnormalLevel(buff1)) { FHTML_SetStr(fhtml0, "bypass_buff1", _blank); FHTML_SetFStr(fhtml0, "button_type1", 36810606, _blank, _blank, _blank, _blank, _blank); }Usage example
if (GetAbnormalLevel(talker, Skill_GetAbnormalType(buff1)) >= Skill_GetAbnormalLevel(buff1)) { FHTML_SetStr(fhtml0, "bypass_buff1", _blank); FHTML_SetFStr(fhtml0, "button_type1", 36810606, _blank, _blank, _blank, _blank, _blank); }
else { FHTML_SetStr(fhtml0, "bypass_buff1", "bypass -h menu_select?ask=-301&reply=1"); FHTML_SetFStr(fhtml0, "button_type1", 36810605, _blank, _blank, _blank, _blank, _blank); }Skill_IsMagicGLOBAL🟢 high
Reports whether a skill is magical (1) or physical (0). Based on this attribute the AI picks a counter-effect: against physical it uses a shield slam, against magic — a silence, and so on. The argument nSkillId is a skill from [skill_pch].
Signature
Skill_IsMagic( int nSkillId )Parameters
nSkillId (int) — the skill.
values — from the [skill_pch] dictionaryExample
if (Skill_IsMagic(Skill01_ID) == 0 && (GetAbnormalLevel(myself.sm, Skill_GetAbnormalType(@s_shield_slam1)) > 0 || GetAbnormalLevel(myself.sm, Skill_GetAbnormalType(@s_curse_of_doom1)) > 0))SetSkillAllGLOBAL🟢 high
Grants a creature all skills at once — a debug/service command. According to the decompile it sends
the server an asynchronous command (like IsToggleSkillOnOff — not an immediate request). Returns no
result to the script. The argument c is who receives them; if c is empty, does nothing.
Signature
SetSkillAll( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature that is granted all skillsExample
SetSkillAll(talker);Usage example
if( reply == 1 ) {
SetSkillAll( talker );
}GetAbnormalLevelGLOBAL🟢 high
Returns the current level of an effect of the given type on a creature: if the effect is absent,
the result is negative (in practice checked as "less than or equal to zero"), and if the
effect is present — its level is greater than zero. Takes a creature (c, CSharedCreatureData,
no namespace) and the effect type (nAbnormalType, int, no namespace), which is almost
always obtained right there via Skill_GetAbnormalType. This is how you check whether a stun is
already on the target, whether it is poisoned, and whether the needed buff is on the player at full strength.
Signature
GetAbnormalLevel( CSharedCreatureData cCreature, int nAbnormalType )Parameters
cCreature (CSharedCreatureData) — whom we check.
nAbnormalType (int) — effect type (usually Skill_GetAbnormalType(s)).Example
i0 = GetAbnormalLevel( myself.sm, Skill_GetAbnormalType( @s_stun_attack11 ) );Usage example
i1 = GetAbnormalLevel( myself.sm, Skill_GetAbnormalType( @s_npc_paralyze1 ) );
if ( i0 <= 0 && i1 <= 0 ) {
if ( Rand( 100 ) < SoulShotRate ) { UseSoulShot( SoulShot ); }
}Skill_GetConsumeMPNPC🟢 high
Returns how much mana (MP) casting the given skill will cost. The AI uses this to check whether the NPC has enough mana to use it. The nSkillId argument is a skill from [skill_pch]; almost always checked together with the HP cost and the reuse delay.
Signature
Skill_GetConsumeMP( int nSkillId )Parameters
nSkillId (int) — skill.
values — from the [skill_pch] dictionaryExample
if ( Skill_GetConsumeMP( DDMagic1 ) < myself.sm.mp && Skill_GetConsumeHP( DDMagic1 ) < myself.sm.hp ) {Usage example
if ( Skill_GetConsumeMP( SetCurse ) < myself.sm.mp && Skill_GetConsumeHP( SetCurse ) < myself.sm.hp && Skill_InReuseDelay( SetCurse ) == 0 ) {
AddUseSkillDesire( attacker, SetCurse, @ST_ATTACK, @AMT_MOVE_TO_TARGET, 1000000 );
}Skill_GetConsumeHPNPC🟢 high
Returns how much health (HP) the cast will cost — for skills that consume health. A full analog of Skill_GetConsumeMP and checked in the same combination. The nSkillId argument is a skill from [skill_pch].
Signature
Skill_GetConsumeHP( int nSkillId )Parameters
nSkillId (int) — skill.
values — from the [skill_pch] dictionaryExample
if ( Skill_GetConsumeMP( DDMagic1 ) < myself.sm.mp && Skill_GetConsumeHP( DDMagic1 ) < myself.sm.hp ) {Usage example
if ( Skill_GetConsumeMP( SetCurse ) < myself.sm.mp && Skill_GetConsumeHP( SetCurse ) < myself.sm.hp && Skill_InReuseDelay( SetCurse ) == 0 ) {
AddUseSkillDesire( attacker, SetCurse, @ST_ATTACK, @AMT_MOVE_TO_TARGET, 1000000 );
}Skill_InReuseDelayNPC🟢 high
Reports whether the skill is on reuse delay: zero means it is ready to use, non-zero means it is still on cooldown. The nSkillId argument is a skill from [skill_pch]. Together with the mana and health cost checks it forms the classic condition "enough resources and cooldown elapsed".
Signature
Skill_InReuseDelay( int nSkillId )Parameters
nSkillId (int) — skill.
values — from the [skill_pch] dictionaryExample
if ( Skill_InReuseDelay( DDMagic1 ) == 0 ) {Usage example
if ( Skill_GetConsumeMP( SetCurse ) < myself.sm.mp && Skill_GetConsumeHP( SetCurse ) < myself.sm.hp && Skill_InReuseDelay( SetCurse ) == 0 ) {
AddUseSkillDesire( attacker, SetCurse, @ST_ATTACK, @AMT_MOVE_TO_TARGET, 1000000 );
}Skill_GetAbnormalTypeNPC🟢 high
Returns the abnormal type of the effect the skill applies — the key by which the presence of the effect on a creature is then queried via GetAbnormalLevel(creature, type). This is how the AI understands whether a stun, poison, or buff is already on the target. The nSkillId argument is a skill from [skill_pch].
Signature
Skill_GetAbnormalType( int nSkillId )Parameters
nSkillId (int) — skill.
values — from the [skill_pch] dictionaryExample
i0 = GetAbnormalLevel( myself.sm, Skill_GetAbnormalType( @s_stun_attack11 ) );Usage example
if ( GetAbnormalLevel( myself.sm, Skill_GetAbnormalType( @s_antaras_regen4 ) ) < 14 ) {
AddUseSkillDesire( myself.sm, @s_antaras_regen4, @ST_ATTACK, @AMT_MOVE_TO_TARGET, 4000000 );
}Skill_GetEffectPointNPC🟢 high
Returns the nominal "effect strength" of a skill. In handlers reacting to someone else's cast, the NPC uses this value to compute how much aggro to add to the caster: the more powerful the skill used against it, the higher the priority of a counterattack. The nSkillId argument is a skill from [skill_pch] (usually skill_name_id, i.e. what was used against the NPC).
Signature
Skill_GetEffectPoint( int nSkillId )Parameters
nSkillId (int) — skill (usually skill_name_id — what was used against the NPC).
values — from the [skill_pch] dictionaryExample
i0 = Skill_GetEffectPoint(skill_name_id);
f1 = Skill_GetEffectPoint(skill_name_id);
i1 = Skill_GetEffectPoint(skill_name_id);Usage example
if ( Skill_GetEffectPoint( skill_name_id ) > 0 ) {
AddAttackDesire( speller, @AMT_STAND, ( ( ( Skill_GetEffectPoint( skill_name_id ) / myself.sm.max_hp ) / 0.050000 ) * 150 ) );
}Skill_GetTargetTypeNPC🟢 high
Returns the skill's target type — an integer enumeration of about two dozen values (self, single target, enemy, own party, corpse, ground point, etc.). The nSkillId argument is a skill from [skill_pch]. The table of types is covered in the structural documentation.
Signature
Skill_GetTargetType( int nSkillId )Parameters
nSkillId (int) — skill.
values — from the [skill_pch] dictionary
Example (illustrative):
Skill_GetTargetType( nSkillId );Skill_HaveAttributeNPC🟢 high
Checks whether the skill has the given element (fire, water, wind, earth, holy, dark — or "no element") and returns a presence flag (1/0). The nSkillId argument is a skill from [skill_pch], nAttribute is the element code. The table of element codes is covered in the structural documentation.
Signature
Skill_HaveAttribute( int nSkillId, int nAttribute )Parameters
nSkillId (int) — skill.
values — from the [skill_pch] dictionary
nAttribute (int) — element code (enum AttributeTypeEnum, see below).Example
if (skill_name_id > 0 && Skill_HaveAttribute(skill_name_id, 0) && Rand(100) < 70 && InMyTerritory(attacker)) {UseSkillNPC🟢 high
Makes the NPC immediately use a skill on the specified target. Unlike AddUseSkillDesire, which merely adds a desire to the queue, UseSkill fires right now — so it is used by buffers handing the player a batch of buffs in a row, and for service casts on itself or on the summoner. The c argument is the target, nSkillId is a skill from [skill_pch].
Signature
UseSkill( CSharedCreatureData cCreature, int nSkillId )Parameters
cCreature (CSharedCreatureData) — skill target.
nSkillId (int) — skill.
values — from the [skill_pch] dictionaryExample
UseSkill( talker, @s_golden_pig_haste );Usage example
if (script_event_arg1 == 18952) {
UseSkill(myself.sm, SelfBuff);
}UseCategorySkillNPC🟢 high
Makes the NPC use one skill from the given category (a set of
skills) on the specified creature. Instead of a specific skill you name the category number, and the needed skill from it
is selected automatically and cast on the target. Returns an integer — a result flag
(whether the cast fired or not); use the return value if you need to know whether the skill was applied.
The category is given as a number (the skill-set number). The returned integer is a result flag
(whether the skill was applied or not), as with its counterpart UseCategoryItem.
Signature
UseCategorySkill( CSharedCreatureData cCreature, int nCategory )Parameters
cCreature (CSharedCreatureData) — on whom to use the skill (cast target).
nCategory (int) — number of the category (skill set) the skill is taken from.
Example (illustrative):
i0 = UseCategorySkill( talker, nCategory );FastBuffNPC🟢 high
A "quick buff" — a service way for NPC buffers to grant a skill by direct identifier and level with a positional index (apparently a slot in the buff list). No direct calls found in the scripts; the argument order is taken from the signature. Arguments: nIndex — index/slot, nSkillID — skill (direct id), nSkillLevel — level.
Signature
FastBuff( int nIndex, int nSkillID, int nSkillLevel )Parameters
nIndex (int) — buff index/slot.
nSkillID (int) — skill (direct id).
nSkillLevel (int) — skill level.
Example (illustrative):
FastBuff( nIndex, nSkillID, nSkillLevel );GetPledgeSkillLevelNPC🟢 high
Returns the level of clan (pledge) skills of a creature and often serves as a gating condition in clan quests and dialogs — for example, access opens only when the clan-skill level is at least four. The c argument is whom to check (usually talker).
Signature
GetPledgeSkillLevel( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — whom to check (usually talker).Example
i0 = GetPledgeSkillLevel(talker);Usage example
if ( GetPledgeSkillLevel( myself.c_ai0 ) < pledge_lv_req ) {
return;
}DeleteAcquireSkillsNPC🟢 high
Deletes a creature's learned skills of the specified category (subclass reset, transformations, etc.).
The second argument is the skill category SkillAcquireType (per the server source), from the
manual_pch dictionary as @..._skill_acquire.
Signature
DeleteAcquireSkills( CSharedCreatureData c, int nAcquireType )Parameters
c (CSharedCreatureData) — whose skills to delete.
nAcquireType (int) — skill category (engine enum SkillAcquireType):
-1 none, 0 regular, 1 fishing, 2 clan, 3 clan sub-unit skills,
4 transformations, 5 subclass, 6 gathering, 7 Bishop-share, 8 Elder-share,
9 SilenElder-share, 10..24 extended sets, 25 fishing (non-dwarf),
26 premium account, 27 academy member, 28..33 racial (human/elf/dark-elf/orc/dwarf/kamael),
34 alchemy. The tail numbers shift per chronicle (manual_pch [*_skill_acquire]).Example
DeleteAcquireSkills(talker, @subjob_skill_acquire);IsToggleSkillOnOffNPC🟢 high
Relates to toggle skills — checking or toggling the on/off state of a skill on the target. The return type in the signature is void (despite the Is... name), which is ambiguous; no direct calls. The pTarget argument is whose skill, nSkillUid is the toggle skill from [skill_pch].
Signature
IsToggleSkillOnOff( CSharedCreatureData pTarget, int nSkillUid )Parameters
pTarget (CSharedCreatureData) — whose.
nSkillUid (int) — toggle skill.
values — from the [skill_pch] dictionaryExample
IsToggleSkillOnOff(myself.sm, @s_i_orfen_speed);
IsToggleSkillOnOff(myself.sm, @s_echimus_ultimate_shield1);ShowSkillListNPC🟢 high
Opens for the player a window listing the skills they can learn from this NPC teacher.
The skill list is selected by the player's own class and level — you do not need to enumerate it.
The first argument is who gets the window (usually talker). The second is the name of your own HTML page for the window:
in all real calls it is empty ("" or _blank), in which case the standard class skill list
window opens. Specifying your own page name only makes sense if you want to show
your own styled page instead of the standard one.
Signature
ShowSkillList( CSharedCreatureData c, string sListName )Parameters
c (CSharedCreatureData) — who gets the window (usually talker).
sListName (string) — name of your own HTML page for the window; empty ("" / _blank) — the standard
class skill list window.Example
ShowSkillList( talker, "" );
ShowSkillList( talker, _blank );Usage example
if ( IsInCategory( @dwarf_bounty_class, talker.occupation ) ) {
ShowSkillList( talker, "" );
} else {
ShowPage( talker, fnClassMismatch );
}ShowEtcSkillListNPC🟢 high
Opens for the player a window listing "other" skills — not the regular class skills, but a separate set:
clan skills, clan sub-unit skills, transformations, subclass, etc. Which exact set the window
shows is determined by the second argument — the type of skill set to learn. In real calls this is either
a named constant (e.g. @pledge_skill_acquire — clan skills) or the same number directly
(3 — clan sub-unit skills). The third argument is the name of your own HTML page for the window: in calls it is
empty ("" / _blank), in which case the standard window for the set opens. A custom page name is given
only for custom window styling.
Signature
ShowEtcSkillList( CSharedCreatureData c, int nAcquireType, string sListName )Parameters
c (CSharedCreatureData) — who gets the window (usually talker).
nAcquireType (int) — type of skill set to learn (which list to show):
-1 none, 0 regular, 1 fishing, 2 clan, 3 clan sub-unit skills,
4 transformations, 5 subclass, 6 gathering, 7 Bishop-share, 8 Elder-share,
9 SilenElder-share, 10..24 extended, 25 fishing (non-dwarf), 26 premium,
27 academy member, 28..33 racial, 34 alchemy. In scripts written as a constant
(@pledge_skill_acquire, @subjob_skill_acquire) or a number. The tail numbers
shift per chronicle — check against manual_pch [*_skill_acquire].
sListName (string) — name of your own HTML page for the window; empty ("" / _blank) — standard window.Example
ShowEtcSkillList( talker, @subjob_skill_acquire, "" );Usage example
if ( reply == 0 ) {
ShowEtcSkillList( talker, skill_acquire, "" );
}ShowEnchantSkillListNPC🟢 high
Opens the skill enchant window for the player. This is a purely presentational command (the engine sends
the client a window-open packet; returns nothing). The engine fills in the player's slots itself; the numeric
script arguments are forwarded to the client as window fields. The first argument c is who gets the window,
the second is a numeric window parameter. Related windows of the same nature: ShowEnchantSkillListDrawer,
ShowEnchantSkillMessage, ShowGrowSkillMessage/…2 (they differ in packet code and field count).
Signature
ShowEnchantSkillList( CSharedCreatureData c, int nEnchantType )Parameters
c (CSharedCreatureData) — who gets the window (usually talker).
nEnchantType (int) — enchant mode (engine enum SkillEnchantType):
0 regular enchant, 1 safe, 2 enchant reset (untrain), 3 route change.Example
ShowEnchantSkillList( talker, state );
ShowEnchantSkillList(talker, action_id);Usage example
if ( talker.level > 75 ) {
ShowEnchantSkillList( talker, state );
} else {
ShowPage( talker, fnLevelMismatch );
}ShowEnchantSkillListDrawerNPC🟢 high
Expands for the player the enchant panel for a specific selected skill — the expanded list
of options that appears when the player clicks a skill in the enchant window. In scripts it is called
from the click handler of that window: two values arrive there — which skill the player selected
(skill_name_id) and what they want to do with it (action_id, the enchant kind) — and you simply pass
them here. Usually conditions are checked before expanding the panel (for example, that the player is not
transformed), and only then this function is called.
Signature
ShowEnchantSkillListDrawer( CSharedCreatureData c, int nSkillUid, int nEnchantType )Parameters
c (CSharedCreatureData) — who gets the panel (usually talker).
nSkillUid (int) — which skill is being enchanted; in scripts this is skill_name_id, coming from
the skill-selection event in the enchant window (a value from the [skill_pch] dictionary).
nEnchantType (int) — what is done with the skill (enchant kind); in scripts this is action_id from the
same event. Values:
0 regular enchant, 1 safe, 2 enchant reset, 3 route change.Example
ShowEnchantSkillListDrawer(talker, skill_name_id, action_id);ShowEnchantSkillMessageNPC🟢 high
Shows the player a short hint message about skill enchanting — what exactly the selected
enchant operation will give for the selected skill. In scripts it is called right after the player selects
a skill in the enchant window: the handler receives which skill they selected (skill_name_id) and which kind
of enchant they want (action_id), and you pass them here so the player sees an explanatory message before
confirming.
Signature
ShowEnchantSkillMessage( CSharedCreatureData c, int nSkillUid, int nEnchantType )Parameters
c (CSharedCreatureData) — who gets the message (usually talker).
nSkillUid (int) — which skill the message is about; in scripts this is skill_name_id, coming from
the skill-selection event in the enchant window (a value from the [skill_pch] dictionary).
nEnchantType (int) — which enchant kind the message is about; in scripts this is action_id from the same
event. Values:
0 regular enchant, 1 safe, 2 enchant reset, 3 route change.Example
ShowEnchantSkillMessage(talker, skill_name_id, action_id);ShowGrowSkillMessageNPC🟢 high
Shows the player a hint message that a skill can be "grown" — its level raised
at an NPC teacher. The first argument is who gets it (usually talker), the second is which
skill the message is about (skill_name_id). The third is the name of your own HTML page for the window: in real calls it is
empty ("" / _blank), in which case the standard message is shown. This function is often called
for regular skills, while for "other" ones (clan, etc.) — its relative ShowGrowEtcSkillMessage,
choosing between them by set type.
Signature
ShowGrowSkillMessage( CSharedCreatureData c, int nSkillUid, string sListName )Parameters
c (CSharedCreatureData) — who gets it (usually talker).
nSkillUid (int) — which skill the message is about; in scripts this is skill_name_id (a value from
the [skill_pch] dictionary).
sListName (string) — name of your own HTML page for the window; empty ("" / _blank) — standard
message.Example
ShowGrowSkillMessage( talker, skill_name_id, "" );
ShowGrowSkillMessage(talker, skill_name_id, _blank);Usage example
if (i0 == 0) {
ShowGrowSkillMessage(talker, skill_name_id, _blank);
} else
if (i0 >= 1) {
ShowGrowEtcSkillMessage(talker, skill_name_id, i0, _blank);
}ShowGrowSkillMessage2NPC🟢 high
An extended variant of ShowGrowSkillMessage: shows the player the same skill "growth" message,
but takes two additional numeric arguments between the skill and the window page name. The
server does not interpret these two numbers — it inserts them into the message text, and the client renders it (by
meaning they are skill growth parameters, e.g. levels). The first argument is who gets it,
the last is the name of your own HTML page for the window (empty — standard message). If the two
additional numbers are not needed, use the regular ShowGrowSkillMessage.
Signature
ShowGrowSkillMessage2( CSharedCreatureData c, int nSkillUid, int nParam1, int nParam2, string sListName )Parameters
c (CSharedCreatureData) — who gets it (usually talker).
nSkillUid (int) — which skill the message is about (a value from the [skill_pch] dictionary).
nParam1 (int) — numeric field of the growth message (inserted by the client; by meaning — a skill growth parameter, e.g. a level).
nParam2 (int) — second such numeric field of the message (inserted by the client).
sListName (string) — name of your own HTML page for the window; empty ("") — standard message.
Example (illustrative):
ShowGrowSkillMessage2( talker, nSkillUid, nParam1, nParam2, "" );ShowGrowEtcSkillMessageNPC🟢 high
The same skill "growth" message as ShowGrowSkillMessage, but for "other" skills —
not ordinary class skills, but a separate set (clan skills, clan sub-unit skills, etc.).
Therefore there is an additional argument here — the type of the skill set to which the growing
skill belongs. In scripts this function and ShowGrowSkillMessage are usually placed in a branch: if the skill is
from the ordinary set — ShowGrowSkillMessage is called, if from the other one — this one, passing the set
type. The last argument is the name of your own HTML page for the window (empty — the standard message).
Signature
ShowGrowEtcSkillMessage( CSharedCreatureData c, int nSkillUid, int nAcquireType, string sListName )Parameters
c (CSharedCreatureData) — whom to show (usually talker).
nSkillUid (int) — about which skill the message is; in scripts this is skill_name_id (a value from
the [skill_pch] dictionary).
nAcquireType (int) — the type of the skill set to which the growing skill belongs:
-1 none, 0 ordinary, 1 fishing, 2 clan, 3 clan sub-unit skills, 4 transformations,
5 subclass, 6 collection, 7 Bishop-share, 8 Elder-share, 9 SilenElder-share, 10..24 extended,
25 fishing (non-dwarf), 26 premium, 27 academic, 28..33 racial, 34 alchemy.
In scripts they write it as a constant (@pledge_skill_acquire) or a number. The tail numbers
shift by chronicle — verify against manual_pch [*_skill_acquire].
sListName (string) — the name of your own HTML page for the window; empty ("" / _blank) — the standard
message.Example
ShowGrowEtcSkillMessage(talker, skill_name_id, @pledge_skill_acquire, _blank);Usage example
if (i0 >= 1) {
ShowGrowEtcSkillMessage(talker, skill_name_id, i0, _blank);
}DispelNPC🟢 high
Removes from a creature an effect of the specified type — the reverse action to GetAbnormalLevel.
Takes a creature (c, CSharedCreatureData, no namespace) and the effect type
(nAbnormalType, int, no namespace), which, as before, is usually taken from a skill
via Skill_GetAbnormalType. With this an NPC drops, for example, its own temporary
protective buff before a battle-phase change.
Signature
Dispel( CSharedCreatureData c, int nAbnormalType )Parameters
c (CSharedCreatureData) — from whom to remove the effect.
nAbnormalType (int) — the abnormal effect type (usually Skill_GetAbnormalType(@skill);
an open set of types from skilldata.txt, there is no fixed enum).Example
Dispel(myself.sm, Skill_GetAbnormalType(@s_trance1));Usage example
if ( ( ( ( talker.transformID == 260 ) || ( talker.transformID == 8 ) ) ) || ( talker.transformID == 9 ) ) {
Dispel( talker, Skill_GetAbnormalType( @s_flying_form_shooting1 ) );
}CastBuffForAgitManagerNPC🟢 high
Applies one buff to a creature — the skill given by the second argument — with mana consumption by the
NPC manager. There is no fixed set: exactly the skill that was passed is cast, and a "series" of
clan hall buffs is done by several calls in a row. Takes a creature (usually talker) and
the buff skill. An important clarification about "large numbers": a value like 284557314 is NOT a separate
server id, but an ordinary [skill_pch] constant written as a number (the packing "skill id << 16 |
level": 284557314 = skill 4342, level 2). That is, the symbolic @-form and this number are
one and the same. If a creature is not passed, the function logs an error and does nothing. Functions close in meaning that give a
buff as a quest reward — CastBuffForQuestReward and its second version — are described in the
quests group.
Signature
CastBuffForAgitManager( CSharedCreatureData c, int nSkill )Parameters
c (CSharedCreatureData) — whom to buff (usually talker).
nSkill (int) — the buff skill (in scripts — a direct id, the packing id<<16|level).
the values are from the [skill_pch] dictionaryExample
CastBuffForAgitManager(talker, reply);TIMERS (Timer)
7 functionsAddTimerExGLOBAL🟢 high
Schedules a one-shot firing: after nTimeout milliseconds the engine will call
TIMER_FIRED_EX with the given identifier nTimerId. Arguments: nTimerId (an arbitrary
id, which the handler will also receive) and nTimeout (the delay until firing, ms), both without
namespace; returns nothing. To make a timer periodic, it is usually
restarted from inside the TIMER_FIRED_EX handler itself, calling the function again with the same id. Available
both on ordinary NPCs and on spawners — with the same meaning.
Related event: the timer is caught by the TIMER_FIRED_EX(timer_id) event; on a maker — ON_TIMER (see NASC_HANDLERS).
Signature
AddTimerEx( int nTimerId, int nTimeout )Parameters
nTimerId (int) — an arbitrary id (which `TIMER_FIRED_EX` will also receive).
nTimeout (int) — the delay until firing, ms.Example
AddTimerEx( 1, 7000 );Usage example
if ( MoveAroundSocial > 0 || MoveAroundSocial1 > 0 ) {
AddTimerEx( 1671, 10000 );
}RegToRespawnTimerMAKER🟢 high
Registers a spawn define in the respawn timer (spawner mechanics): after
an NPC dies, it schedules its reappearance. The nRespawnTime argument is the absolute
moment of revival (no namespace); returns an integer. Belongs to the spawn-define
class, not to an ordinary NPC.
Signature
RegToRespawnTimer( int nRespawnTime )Parameters
nRespawnTime (int) — the absolute respawn moment = death_time + respawn_time of the spawn
define (the creature's death time plus the revival interval from loaded_def).Example
def0.RegToRespawnTimer(i0);AtomicAddTimerExNPC🟢 high
An "atomic" timer scheduling bound to creature c: sets the timer only
if no such timer exists yet, and returns a success flag (presumably TRUE if
set, FALSE if it already existed). Arguments: c (the creature owning the timer,
CSharedCreatureData), nTimerId (timer id) and nTimeout (delay, ms), all without a
namespace. In essence this is a protective "lock" for timers.
Related event: the timer is caught by the TIMER_FIRED_EX(timer_id) event (see NASC_HANDLERS).
Signature
AtomicAddTimerEx( CSharedCreatureData c, int nTimerId, int nTimeout )Parameters
c (CSharedCreatureData) — the creature owning the timer.
nTimerId (int) — timer id (an arbitrary number chosen by the script).
nTimeout (int) — delay, ms.
Example (illustrative):
AtomicAddTimerEx( talker, nTimerId, nTimeout );BlockTimerNPC🟢 high
Suspends (blocks) the timer with the given identifier — its firings stop
reaching TIMER_FIRED_EX. Argument: nTimerId (id of the timer being blocked, no
namespace); returns nothing. Used to temporarily disable periodic
logic (for example, during a special combat phase) or to silence a group of timers at once.
Signature
BlockTimer( int nTimerId )Parameters
nTimerId (int) — id of the timer being blocked.Example
BlockTimer(1001);Usage example
if ( myself.i_ai2 == 0 ) {
BlockTimer( CHECK_TIME_ANNOUNCE );
myself.i_ai2 = 1;
AddTimerEx( CHECK_TIME_ANNOUNCE2, ( 1 * 100 ) );
}UnblockTimerNPC🟢 high
Removes the block imposed by BlockTimer — the timer works again. Argument:
nTimerId (id of the timer being unblocked, no namespace); returns nothing. Usually
paired with BlockTimer: switched off for the duration of a phase — switched back on.
Signature
UnblockTimer( int nTimerId )Parameters
nTimerId (int) — id of the timer being unblocked.Example
UnblockTimer(1001);SetTimerPeriodNPC🟢 high
Sets the period of the NPC's periodic system timer — how often the engine invokes
the regular handler. Argument: nPeriodMs (tick period in milliseconds); returns
nothing. Affects the frequency of regular AI logic (1800 ms in the calls).
Signature
SetTimerPeriod( int nPeriodMs )Parameters
nPeriodMs (int) — tick period, ms (1800 in the calls).Example
SetTimerPeriod(1800);SetTimerPeriodByTickNPC🟢 high
Same as SetTimerPeriod, but the period is specified in server ticks rather than
milliseconds. Argument: nPeriod (period in server ticks, no namespace); returns
nothing. The meaning is inferred from the name; no direct calls were extracted.
Signature
SetTimerPeriodByTick( int nPeriodTicks )Parameters
nPeriodTicks (int) — tick period, in server ticks.
Example (illustrative):
SetTimerPeriodByTick( nPeriodTicks );DESIRES (DESIRE)
32 functionsAddAttackDesireNPC🟢 high
The most basic combat desire. The character starts hitting the specified creature
with an ordinary attack and holds on to that target as long as the desire remains foremost in the queue.
It takes three things: whom to attack (a creature — usually the one who just
hit the NPC), how to move while doing so (the nMoveType parameter), and how strongly
this is wanted (the weight).
The nMoveType values are covered below, in the "Parameters" section. Sometimes instead of a
constant there is the expression IsWalkedNpc, which itself computes 0 or 1.
Related event: on completion — ATTACK_FINISHED(target), on failure — ATTACK_INTERRUPTED (see NASC_HANDLERS).
Signature
AddAttackDesire( CSharedCreatureData cCreature, int nMoveType, float fDesireValue )Parameters
cCreature (CSharedCreatureData) — the attack target (a creature). Usually attacker, creature, c0, target.master.
nMoveType (int) — the way of moving toward the target while performing the desire
Constants from [manual_pch] are used:
@AMT_STAND (0) — attack in place, without closing in
@AMT_MOVE_TO_TARGET (1) — approach the target closely and attack (pursue)
fDesireValue (float) — the desire's priority (the higher — the sooner it is fulfilled).
Example. A monster took a hit and rushes at its offender:
AddAttackDesire( attacker, @AMT_MOVE_TO_TARGET, 2000 );
Here `attacker` is the assailant, `@AMT_MOVE_TO_TARGET` is "pursue", 2000 is the weight.
The same technique with a different target — for example, a helper rushes at the owner's target:
AddAttackDesire( c0, @AMT_MOVE_TO_TARGET, 500 );Usage example
if ( creature.karma > 0 ) {
AddAttackDesire( creature, @AMT_MOVE_TO_TARGET, 1500 );
}AddAttackDesireExNPC🟢 high
The same as AddAttackDesire, but with two differences. First, the target
is specified not by a creature reference but by its numeric object-id (usually
obtained in advance by functions like GetObjectID). Second, there appears a force
flag nForce — judging by scripts, it makes the desire fire more
forcefully (the value 1 is found in combat files; the exact meaning is deferred to questions).
Related event: on completion — ATTACK_FINISHED(target), on failure — ATTACK_INTERRUPTED (see NASC_HANDLERS).
Signature
AddAttackDesireEx( int nTargetObjectId, int nMoveType, int nForce, float fDesireValue )Parameters
nTargetObjectId (int) — the object-id of the target (for example, i0, the result of GetObjectID/GetCreatureID).
nMoveType (int) — the way of moving toward the target while performing the desire
Constants from [manual_pch] are used:
@AMT_STAND (0) — attack in place, without closing in
@AMT_MOVE_TO_TARGET (1) — approach the target closely and attack (pursue)
nForce (int) — the force flag: 1 = fulfill the desire bypassing checks (range, mana, etc.); 0 = with checks.
fDesireValue (float) — the desire's priority.Example
AddAttackDesireEx( i0, @AMT_MOVE_TO_TARGET, 1, 100 );
Attack the creature with identifier i0, pursuing it, in forced
mode, with weight 100.Usage example
if ( Rand( 100 ) < 30 ) {
AddAttackDesireEx( i0, @AMT_MOVE_TO_TARGET, 1, 100 );
}AddUseSkillDesireNPC🟢 high
One of the most frequent desires. Makes the character use a skill on a chosen
target. You need to specify the target, the skill identifier, its nature (offensive or
supporting), the way of moving, and the weight.
It is important to understand the "skill nature + target" pairing. If the skill is offensive
(@ST_ATTACK), the target is an enemy; if supporting (@ST_HEAL) — an ally or
the character itself (myself.sm — the owner).
The skill_type and nMoveType values are covered below, in the "Parameters" section; the same
two sets are used by all functions of the AddUseSkillDesire family (including
the Ex variants and AddUseOneTimeSkillDesire).
Related event: start — USE_SKILL_STARTED, completion — USE_SKILL_FINISHED(target, skill_name_id, success), failure — USE_SKILL_INTERRUPTED (see NASC_HANDLERS).
Signature
AddUseSkillDesire( CSharedCreatureData cCreature, int nSkillNameID, int skill_type, int nMoveType, float fDesireValue )Parameters
cCreature (CSharedCreatureData) — the skill target (an enemy for an attack, an ally/myself.sm for healing).
nSkillNameID (int) — the skill ID (@s_*).
the values are from the [skill_pch] dictionary
skill_type (int) — the skill nature: offensive (on an enemy) or supporting (on an ally/self)
Constants from [manual_pch] are used:
@ST_ATTACK (0) — an offensive skill — used on an enemy
@ST_HEAL (1) — support: heal/buff — on an ally or on self
nMoveType (int) — the way of moving toward the target while performing the desire
Constants from [manual_pch] are used:
@AMT_STAND (0) — attack in place, without closing in
@AMT_MOVE_TO_TARGET (1) — approach the target closely and attack (pursue)
fDesireValue (float) — the desire's priority.
Example of an offensive skill. An NPC casts a curse of fear on the attacker,
without moving from its spot, with maximum priority:
AddUseSkillDesire(attacker, @s_curse_fear_chance30, @ST_ATTACK, @AMT_STAND, 1000000000);
Example of support. A summoned creature heals/empowers its owner, having approached
it more closely:
AddUseSkillDesire(myself.sm, SpecialSkill, @ST_HEAL, @AMT_MOVE_TO_TARGET, 1000000);Usage example
if ( Skill_GetConsumeMP( SetCurse ) < myself.sm.mp && Skill_GetConsumeHP( SetCurse ) < myself.sm.hp && Skill_InReuseDelay( SetCurse ) == 0 ) {
AddUseSkillDesire( attacker, SetCurse, @ST_ATTACK, @AMT_MOVE_TO_TARGET, 1000000 );
}AddUseSkillDesireExNPC🟢 high
A development of AddUseSkillDesire for finer cases. The target is specified by
object-id, and two additional parameters are added: the force flag
nForce and the desire flag nDesireFlag (in scripts it is almost always 0; the set of its
possible values is clarified in questions).
Related event: start — USE_SKILL_STARTED, completion — USE_SKILL_FINISHED(target, skill_name_id, success), failure — USE_SKILL_INTERRUPTED (see NASC_HANDLERS).
Signature
AddUseSkillDesireEx( int nTargetObjectId, int nSkillNameID, int skill_type, int nMoveType, int nForce, float fDesireValue, int nDesireFlag )Parameters
nTargetObjectId (int) — the object-id of the target.
nSkillNameID (int) — the skill ID.
the values are from the [skill_pch] dictionary
skill_type (int) — the skill nature: offensive (on an enemy) or supporting (on an ally/self)
Constants from [manual_pch] are used:
@ST_ATTACK (0) — an offensive skill — used on an enemy
@ST_HEAL (1) — support: heal/buff — on an ally or on self
nMoveType (int) — the way of moving toward the target while performing the desire
Constants from [manual_pch] are used:
@AMT_STAND (0) — attack in place, without closing in
@AMT_MOVE_TO_TARGET (1) — approach the target closely and attack (pursue)
nForce (int) — the force flag (1 = bypassing range/mana checks).
fDesireValue (float) — the desire's priority.
nDesireFlag (int) — the bit flag of the desire's "non-replaceability" (in scripts usually 0). There are "non-replaceability" bits: for a skill desire (one-time, non-removable) and for an attack desire (absolute).
Example — a summoner distributes skills on the owner's target:
AddUseSkillDesireEx(myself.sm.master.target_id, step0_skill01, @ST_ATTACK, reply, ask, 1000000, 0);
The target is what the summoner's owner is attacking; the move type and force flag
are taken from the variables reply and ask, the weight is a million, the additional flag is 0.Usage example
if ( Skill_GetConsumeMP( DDMagic ) < myself.sm.mp && Skill_GetConsumeHP( DDMagic ) < myself.sm.hp && Skill_InReuseDelay( DDMagic ) == 0 ) {
AddUseSkillDesireEx( myself.sm.id, DDMagic, 0, reply, ask, 1000000, 0 );
}AddMoveToDesireNPC🟢 high
Sends the character to a specific world point with the given coordinates X, Y, Z.
Most often this is how NPCs are returned "home", to their spawn spot, after a fight
has ended.
Related event: on arrival — MOVE_TO_FINISHED(x, y, z), on failure — MOVE_TO_INTERRUPTED (see NASC_HANDLERS).
Signature
AddMoveToDesire( int nX, int nY, int nZ, float fDesire )Parameters
nX (int) — the X coordinate of the destination point the character goes to
nY (int) — the Y coordinate of the destination point the character goes to
nZ (int) — the Z coordinate of the destination point the character is sent to
fDesire (float) — the weight (priority) of the desire to go to the specified point
Example — return to the spawn point:
AddMoveToDesire( myself.start_x, myself.start_y, myself.start_z, 30 );
The coordinates are taken from start_x/start_y/start_z saved at birth, the weight is
small (30) — this is a calm background return that any combat desire will easily override.Usage example
if ( timer_id == 2001 ) {
AddMoveToDesire( ( Dest_X + Rand( 400 ) ), ( Dest_Y + Rand( 400 ) ), Dest_Z, 5 );
}AddFleeDesireNPC🟢 high
The character starts fleeing from the specified creature. A typical scenario —
a cowardly monster or a wounded NPC with little health.
Related event: on completion — FLEE_FINISHED(target), on failure — FLEE_INTERRUPTED (see NASC_HANDLERS).
Signature
AddFleeDesire( CSharedCreatureData cCreature, float fDesire )Parameters
cCreature (CSharedCreatureData) — the creature the character flees from
fDesire (float) — the weight (priority) of the desire to fleeExample
AddFleeDesire(creature, 1000000);
Flee from `creature` with high priority, so that the desire confidently overrides
the desire to fight.Usage example
if ( myself.i_ai2 == 1 ) {
AddFleeDesire( attacker, 5000 );
}AddFollowDesireNPC🟢 high
Makes the character stay close to the specified creature and walk after it.
Often used by minions who follow their boss (myself.boss).
Related event: on completion — FOLLOW_FINISHED(target), on failure — FOLLOW_INTERRUPTED (see NASC_HANDLERS).
Signature
AddFollowDesire( CSharedCreatureData cCreature, float fDesire )Parameters
cCreature (CSharedCreatureData) — the creature the character follows and stays close to
fDesire (float) — the weight (priority) of the desire to follow the specified creatureExample
AddFollowDesire(myself.boss, 5);
A small weight (5) is appropriate here: following is a calm background behavior
that will yield to a fight at any moment.Usage example
if ( creature.is_pc == 1 && Rand( 100 ) < 50 ) {
AddFollowDesire( creature, 100 );
}AddMoveAroundDesireNPC🟢 high
A light "idle" behavior: the character does not stand like a post, but moves slightly in
the vicinity. The first parameter sets the duration/interval of wandering (in scripts
usually 5–10), the second — the weight.
Related event: on completion — MOVE_AROUND_FINISHED, on failure — MOVE_AROUND_INTERRUPTED (see NASC_HANDLERS).
Signature
AddMoveAroundDesire( int time, float fDesire )Parameters
time (int) — the duration/interval of wandering in the vicinity (usually 5–10)
fDesire (float) — the weight (priority) of the desire to move slightly in the vicinity
Example of a peaceful NPC:
AddMoveAroundDesire(5, 5);Usage example
if ( IsWalkedNpc == 1 ) {
AddMoveAroundDesire( 5, 5 );
}RemoveDesireNPC🟢 high
Removes from the queue all desires of the given type. The single argument is the
desire type code (the PhysicalState/PSTATE enumeration). A stable core, the same in all
chronicles: 0 — idle, 1 — wander, 2 — stand empty, 3 — attack, 4 — pursue,
5 — flee, 6 — pick up an item, 7 — follow, 8 — decay, 9 — walk waypoints,
10 — use a skill, 11 — go to a point, 12 — social action. Codes above 12
(approach the target, super point, etc.) are numbered differently in different chronicles — the exact
table by chronicle is given in the structural NASC_FUNCTIONS.md. In practice, only codes from the
stable core are found in scripts: for example, RemoveDesire(11) removes all
"go to coordinates" desires. The same set of codes is used by GetTopDesireValue.
Signature
RemoveDesire( int nDesireType )Parameters
nDesireType (int) — the desire type code (PhysicalState/PSTATE): 0 idle · 1 wander · 2 stand ·
3 attack · 4 pursue · 5 flee · 6 pick up item · 7 follow · 8 decay ·
9 walk waypoints · 10 use skill · 11 go to point · 12 social action. Codes >12
are numbered differently in different versions (the full table — in NASC_FUNCTIONS.md).Example
RemoveDesire(11);RemoveAllDesireNPC🟢 high
Completely clears the desire queue — the character "forgets" what it was going to do.
Convenient to call before changing an AI state, so that the old behavior does not interfere
with the new one.
Signature
RemoveAllDesire( )Parameters
(none — the function is called without arguments)Usage example
if ( myself.sm.db_value == 0 ) {
RemoveAllDesire( );
}AddMoveToTargetDesireNPC🟢 high
Unlike AddMoveToDesire, which leads the character to a stationary point with
coordinates, this function brings it closer to a moving target and keeps a given
distance. The target is specified by identifier, followed by the desired distance, a
service flag (in scripts usually 0), and the weight.
AddMoveToTargetDesire(h1.creature.id, 150, 0, 1000);
Approach the creature h1.creature to 150 units.
Related event: on arrival — MOVE_TO_FINISHED, on failure — MOVE_TO_INTERRUPTED (see NASC_HANDLERS).
Signature
AddMoveToTargetDesire( int nTargetObjectId, int nDistance, int nDesireFlag, float fDesire )Parameters
nTargetObjectId (int) — the identifier of the moving target the character approaches
nDistance (int) — the desired distance kept from the target
nDesireFlag (int) — a service mode flag (in scripts usually 0)
fDesire (float) — the weight (priority) of the desire to approach the moving target and keep the distanceUsage example
if (IsNullCreature(myself.c_ai0) == 0) {
AddMoveToTargetDesire(myself.c_ai0.id, 150, 0, 10000);
}AddChaseDesireNPC🟢 high
Combat chasing: the character runs after the specified creature. Takes the target and
the weight. In meaning it is close to the "follow + attack" pairing, but this is a separate
standalone chase desire.
Related event: on completion — CHASE_FINISHED, on failure — CHASE_INTERRUPTED (see NASC_HANDLERS).
Signature
AddChaseDesire( CSharedCreatureData cCreature, float fDesire )Parameters
cCreature (CSharedCreatureData) — the creature the combat chase (pursuit) is conducted after
fDesire (float) — the weight (priority) of the desire to chase the target
Example (illustrative):
AddChaseDesire( talker, 0.0 );AddFleeDesireExNPC🟢 high
The same fleeing as AddFleeDesire, only now you can directly specify to what
distance to run off. Convenient when you need not just to "escape", but to bounce off to a
specific distance and, for example, start shooting from afar.
AddFleeDesireEx( attacker, 300, 100000 );
Run off from the attacker by 300 units with high priority.
Related event: on completion — FLEE_FINISHED(target), on failure — FLEE_INTERRUPTED (see NASC_HANDLERS).
Signature
AddFleeDesireEx( CSharedCreatureData cCreature, int nDistance, float fDesire )Parameters
cCreature (CSharedCreatureData) — the creature the character runs off from
nDistance (int) — the distance to run off from the creature
fDesire (float) — the weight (priority) of the desire to flee to the given distanceUsage example
if ( private == myself.boss ) {
AddFleeDesireEx( private, 500, 10000000 );
}AddFollowDesire2NPC🟢 high
Advanced following. A plain AddFollowDesire just trails after the target, while here
you can set the exact place next to it: at what distance to keep and at what
angle to stand. The angle is measured in degrees — 0 is in front, 90 to the right, 180
behind, 270 to the left; for convenience there are ready names eAFD2_DEGREE_FRONT, _RIGHT,
_BACK, _LEFT. The follow type chooses the way of holding position: by distance and
angle (eAFD2_FT_DIST_AND_DEGREE) or by axis offset (eAFD2_FT_XY_GAP).
AddFollowDesire2(myself.c_ai0, 9, @eAFD2_FT_DIST_AND_DEGREE, 250, @eAFD2_DEGREE_FRONT);
Keep 250 units strictly in front of the ally. This is how retinues and
escort formations are built.
Related event: on completion — FOLLOW_FINISHED(target), on failure — FOLLOW_INTERRUPTED (see NASC_HANDLERS).
Signature
AddFollowDesire2( CSharedCreatureData cCreature, float value, int follow_type, int dist, int angle )Parameters
cCreature (CSharedCreatureData) — the creature the character follows, taking a position beside it
value (float) — the desire weight (following priority)
follow_type (int) — the position-holding type: by distance and angle or by axis offset
dist (int) — the distance to keep from the target while following
angle (int) — the position angle relative to the target in degrees (0 in front, 90 right, 180 behind, 270 left); the constants `eAFD2_DEGREE_FRONT`/`_RIGHT`/`_BACK`/`_LEFT` can be usedUsage example
if ( IsNullCreature( myself.boss ) == 0 ) {
AddFollowDesire2( myself.boss, 100, 1, ( 150 + Rand( 150 ) ), ( 90 + Rand( 180 ) ) );
}AddPetDefaultDesire_FollowNPC🟢 high
Sets a pet's basic "background" desire — to follow its owner. Takes
only the weight. This is that very habit of a tamed beast to walk after its owner when it
is given no other commands.
AddPetDefaultDesire_Follow(20.000000);
Related event: on completion — FOLLOW_FINISHED(target) (see NASC_HANDLERS).
Signature
AddPetDefaultDesire_Follow( float fDesire )Parameters
fDesire (float) — the weight (priority) of the pet's background desire to follow its ownerExample
AddPetDefaultDesire_Follow(20.0);AddMoveAroundLimitedDesireNPC🟢 high
Like AddMoveAroundDesire, only the wandering is limited by a radius — the character does not
go farther than the specified distance from the original point. Three parameters:
duration, weight, and the limiting radius.
AddMoveAroundLimitedDesire(500, 250, 250);
Wander within 250 units.
Related event: on completion — MOVE_AROUND_FINISHED (see NASC_HANDLERS).
Signature
AddMoveAroundLimitedDesire( int time, float fDesire, int nDistance )Parameters
time (int) — the duration/interval of wandering
fDesire (float) — the weight (priority) of the desire to wander in the vicinity
nDistance (int) — the limiting radius of distance from the original point while wanderingExample
AddMoveAroundLimitedDesire(5, 5, 0);AddMoveSuperPointDesireNPC🟢 high
A "super point" is a patrol route predefined in the data. The function
sends the character to walk along such a route: you need to specify its name, the traversal
method, and the weight. The variant with a two at the end adds one more mode flag.
AddMoveSuperPointDesire( SuperPointName, SuperPointMethod, SuperPointDesire );
AddMoveSuperPointDesire2( SuperPointName, SuperPointMethod, SuperPointDesire, 1 );
Example
AddMoveSuperPointDesire("iz_aq_antaras01", @MoveSuperPoint_FollowRail, 100);AddMoveFreewayDesireNPC🟢 high
A close relative of the super point, but the route is specified not by name but by a numeric
identifier. This is how, for example, caravans and vehicles are driven along fixed
roads.
AddMoveFreewayDesire( FreewayID, FreewayMethod, 50 );
Related event: on arrival at nodes — NODE_ARRIVED (see NASC_HANDLERS).
Signature
AddMoveFreewayDesire( int nFreewayID, int nFreewayMethod, float fDesire )Parameters
nFreewayID (int) — the numeric identifier of the freeway route the character moves along.
nFreewayMethod (int) — the traversal method of the route. Known value: @MoveFreeway_Loop = 1
(loop the route). In one and the same call @MoveFreeway_Loop and 1
are interchangeable — hence the constant's value. The script may pass
its own variable FreewayMethod.
fDesire (float) — the weight (priority) of the desire to move along the route (50 / 100 / 99999 in calls).Usage example
if ( FreewayID > -1 && FreewayDesire > 0 ) {
AddMoveFreewayDesire( FreewayID, FreewayMethod, FreewayDesire );
}AddMoveToWayPointDesireNPC🟢 high
Here the route is passed directly as two lists: the coordinates of the waypoints and
the delays at each of them. The character goes from point to point, stopping for the
given time. The third argument is the number of route traversals (1 = one pass,
a counter variable sets the number of repeats), the fourth — the desire weight.
AddMoveToWayPointDesire( WayPoints, WayPointDelays, 1, 10 );
Related event: on completion — MOVE_TO_WAY_POINT_FINISHED, at nodes — NODE_ARRIVED (see NASC_HANDLERS).
Signature
AddMoveToWayPointDesire( WayPointsType WayPoints, WayPointDelaysType WayPointDelays, int nRepeat, float fDesire )Parameters
WayPoints (WayPointsType) — the list of the route's waypoint coordinates.
WayPointDelays (WayPointDelaysType) — the list of delays (stop times) at each point.
nRepeat (int) — the number of route traversals: 1 = one pass; a counter variable (e.g. myself.i_ai1)
sets the needed number of traversal repeats.
fDesire (float) — the weight (priority) of the desire to walk the points (= 10 in calls).Usage example
if ( myself.i_ai1 > 0 ) {
AddMoveToWayPointDesire( WayPoints, WayPointDelays, myself.i_ai1, 10 );
} else {
AddMoveToWayPointDesire( WayPoints, WayPointDelays, 1, 10 );
}AddMoveFormationDesireNPC🟢 high
Gives the NPC the desire to move not on its own, but as part of a formation — this is how a group
of mobs moves in a single order, holding places relative to each other. The key arguments are the group
number and the formation number: in live calls the NPC receives its GroupID (twice) and FormationID,
and it is these that bind it to the other members of the formation (in the script these are class parameters,
by default -1). The last argument is the weight (priority) of the desire, as with all Add*Desire: the
higher it is, the more insistently the NPC holds the formation. Notably, the weight is changed by situation — on
appearance a high one is set (2000), and after arrival at the next waypoint a low one (50),
so that the formation does not override other actions. The formation number references the formation definition from formationinfo.txt (which order exactly to hold).
The first (string) argument is the name of the "super point" (a named route); in calls it is empty.
Signature
AddMoveFormationDesire( string sSuperPoint, int nFreewayId, int nEffectId, int nGroupId1, int nGroupId2, int nFormationId, int nDesireFlag, float fDesire )Parameters
sSuperPoint (string) — the name of the "super point" (a named movement route); in calls an empty string.
nFreewayId (int) — the id of the "freeway" (a movement route/road); in calls constantly 35.
nEffectId (int) — the id of the movement effect; in calls constantly 1.
nGroupId1 (int) — the first formation group (in calls GroupID) — binds members of one formation.
nGroupId2 (int) — the second formation group (in calls the same GroupID).
nFormationId (int) — the formation number from formationinfo.txt — which order exactly to hold.
nDesireFlag (int) — the desire flags; in calls constantly 1.
fDesire (float) — the weight (priority) of the desire to hold the formation; in calls 2000 on appearance and 50 in transit.Example
AddMoveFormationDesire("", 35, 1, GroupID, GroupID, FormationID, 1, 50);AddDoNothingDesireNPC🟢 high
Sometimes the most correct behavior is to freeze. This function holds the character in
inaction for the given time. The first parameter is the duration, the second — the weight.
AddDoNothingDesire( 40, 30 );
Signature
AddDoNothingDesire( int nDuration, float fDesire )Parameters
nDuration (int) — the duration of inaction (how long to stand without actions)
fDesire (float) — the weight (priority) of the desire to do nothingUsage example
if ( x == myself.start_x && y == myself.start_y && z == myself.start_z ) {
AddDoNothingDesire( 40, 30 );
}AddDecayingDesireNPC🟢 high
"Decaying" in Lineage is the stage when the corpse of a killed creature decays and
disappears. The function adds the desire to enter this state; the single
parameter is the weight. Applied when the script itself decides to remove the character from the scene.
Related event: on completion — DECAYING_FINISHED, on failure — DECAYING_INTERRUPTED (see NASC_HANDLERS).
Signature
AddDecayingDesire( float fDesire )Parameters
fDesire (float) — the weight (priority) of the desire to enter the corpse-decay state.
Example (illustrative):
AddDecayingDesire( 0.0 );AddEffectActionDesireNPC🟢 high (confirmed by engine sources)
The desire to play a social action — a bow, gesture, emote — directed at the
specified creature (most often at itself, myself.sm: "a gesture into the void").
The action number chooses the specific animation of the NPC's model (1, 2, 3 … — the first,
second, third social gesture: the client's Social animations). The duration is given
IN MILLISECONDS — which is why in scripts it is often written as the expression
(N * 1000) / 30: this is the conversion of N animation frames at 30 frames per second into
milliseconds. The variant with a two adds as a fifth argument a second duration
(also ms).
This is a "background" desire with a low weight: the typical pairing is a periodic timer
that checks that the NPC is standing idle (myself.p_state, see NASC_LANGUAGE), and with
a chance plays a gesture.
Signature
AddEffectActionDesire( CSharedCreatureData cCreature, int nEffectID, int nEffectDuration, float fDesire )
AddEffectActionDesire2( CSharedCreatureData cCreature, int nEffectID, int nEffectDuration, float fDesire, int nEffectDuration2 )Parameters
cCreature (CSharedCreatureData) — whom the gesture is directed at (usually myself.sm).
nEffectID (int) — the social action/animation number (1, 2, 3 …; the set of gestures
is determined by the model of the specific NPC).
nEffectDuration (int) — the gesture's duration, milliseconds; the notation
(N * 1000) / 30 — the conversion of N frames (30 fps) to ms.
fDesire (float) — the weight (priority) of the desire; for background gestures usually small (50).
nEffectDuration2 (int, only in AddEffectActionDesire2) — the second duration, ms.Example
AddEffectActionDesire(myself.sm, 3, (MoveAroundSocial * 1000) / 30, 50);
AddEffectActionDesire2(myself.sm, 4, 1500, 10000000, 5000);Usage example
EventHandler TIMER_FIRED_EX( timer_id )
{
if (timer_id == 1671) {
if ( ( myself.sm.hp > (myself.sm.max_hp * 0.400000) ) && ( myself.sm.alive != 0 ) && ( myself.p_state != 3 ) ) {
if (MoveAroundSocial > 0 || MoveAroundSocial1 > 0) {
if (MoveAroundSocial > 0 && Rand(100) < 40) {
AddEffectActionDesire( myself.sm, 3, ((MoveAroundSocial * 1000) / 30), 50 );
} else
if (MoveAroundSocial1 > 0 && Rand(100) < 40) {
AddEffectActionDesire( myself.sm, 2, ((MoveAroundSocial1 * 1000) / 30), 50 );
}
}
}
AddTimerEx(1671, 10000);
}
super;
}
A peaceful townsperson, once every 10 seconds, if alive, healthy, and not walking (p_state != 3, that is,
not @ACT_MOVE), with a 40% chance plays one of two configured gestures; the duration is
set by a class parameter in frames and converted to milliseconds.AddGetItemDesireNPC🟢 high
The desire to pick up a lying item. The basic version takes the item itself
(a CSharedItemData object), and the Ex version — its numeric object index. The second
parameter, as usual, is the desire weight.
Where this index comes from is an important question. It arrives from the SEE_ITEM event,
which fires when the NPC notices items lying nearby. The first argument
of this handler is item_index_list, the list of seen items (of type
CItemIndexList). The list has two methods: GetSize gives the number of items, and
GetItemIndex(n) — the object index of the n-th item (it is exactly this that is passed to
AddGetItemDesireEx; this same index can be compared with @-identifiers of items
from [item_pch]). A typical handler looks like this:
EventHandler SEE_ITEM( item_index_list, i0, i1, i2 )
{
i0 = item_index_list.GetSize( ); // how many items are nearby
for( i1 = 0; i1 < i0; ++i1 ) {
AddGetItemDesireEx( item_index_list.GetItemIndex( i1 ), ( 10000 - i1 ) );
}
}
The NPC wants to pick up all the seen items, and for the first ones in the list the weight is higher
(10000 - i1) — it will grab them earlier. Here i0, i1, i2 are the local scratch
variables declared right in the handler header (integers, by the i prefix).
Close in meaning are the function LookItem (make the NPC react to an item) and
the event GET_ITEM_FINISHED, which fires when the pickup is completed.
Related event: on completion — GET_ITEM_FINISHED(item, success), on failure — GET_ITEM_INTERRUPTED; items — from SEE_ITEM (see NASC_HANDLERS).
Example (illustrative):
AddUseOneTimeSkillDesireNPC🟢 high
A full analog of AddUseSkillDesire with all the same parameters (target, skill, its
nature, way of moving, weight), but the desire fires once: the character
uses the skill one time and removes the desire, rather than trying to repeat it.
Related event: start — USE_SKILL_STARTED, completion — USE_SKILL_FINISHED, failure — USE_SKILL_INTERRUPTED (see NASC_HANDLERS).
Signature
AddUseOneTimeSkillDesire( CSharedCreatureData cCreature, int nSkillNameID, int skill_type, int nMoveType, float fDesireValue )Parameters
cCreature (CSharedCreatureData) — the target creature on which the skill is used once
nSkillNameID (int) — the identifier of the skill being used ([skill_pch])
skill_type (int) — the skill nature: offensive (on an enemy) or supporting (on an ally/self)
Constants from [manual_pch] are used:
@ST_ATTACK (0) — an offensive skill — used on an enemy
@ST_HEAL (1) — support: heal/buff — on an ally or on self
nMoveType (int) — the way of moving toward the target while performing the desire
Constants from [manual_pch] are used:
@AMT_STAND (0) — attack in place, without closing in
@AMT_MOVE_TO_TARGET (1) — approach the target closely and attack (pursue)
fDesireValue (float) — the weight (priority) of the one-time desire to use the skill
Example (illustrative):
AddUseOneTimeSkillDesire( talker, nSkillNameID, skill_type, nMoveType, 0.0 );AddUseSkillDesireExByActionNPC🟢 high
An extension of AddUseSkillDesireEx: the identifier of a client action is added to the
usual set of parameters. That is, the use of the skill can be bound to a
specific action on the part of the client/player (for example, a button press).
Related event: start — USE_SKILL_STARTED, completion — USE_SKILL_FINISHED, failure — USE_SKILL_INTERRUPTED (see NASC_HANDLERS).
Signature
AddUseSkillDesireExByAction( int nTargetObjectId, int nSkillNameID, int skill_type, int nMoveType, int nForce, float fDesireValue, int nDesireFlag, int nClientActionId )Parameters
nTargetObjectId (int) — the identifier of the target creature on which the skill is used
nSkillNameID (int) — the identifier of the skill being used
skill_type (int) — the skill nature: offensive (on an enemy) or supporting (on an ally/self)
Constants from [manual_pch] are used:
@ST_ATTACK (0) — an offensive skill — used on an enemy
@ST_HEAL (1) — support: heal/buff — on an ally or on self
nMoveType (int) — the way of moving toward the target while performing the desire
Constants from [manual_pch] are used:
@AMT_STAND (0) — attack in place, without closing in
@AMT_MOVE_TO_TARGET (1) — approach the target closely and attack (pursue)
nForce (int) — the flag/degree of forced skill use
fDesireValue (float) — the weight (priority) of the desire to use the skill
nDesireFlag (int) — a service desire flag (usually 0)
nClientActionId (int) — the identifier of the client action with which the skill use is associatedUsage example
if (step_skill_target01 == 2 && myself.master.alive > 0) {
AddUseSkillDesireExByAction(myself.master.id, step_skill01, @ST_ATTACK, reply, ask, 1000000, 0, action_id);
}RandomizeAttackDesireNPC🟢 high
Shuffles the attack priorities, making the character choose a target anew, more or
less at random from those who anger it. Very beloved in boss scripts: thanks to
it, a raid monster unpredictably switches between players.
Signature
RandomizeAttackDesire( )Parameters
(none — the function is called without arguments)Usage example
if ( Rand( 3 ) < 1 ) {
RandomizeAttackDesire( );
}GetTopDesireValueNPC🟢 high
Returns the weight of the top desire of the given type (the same type code as RemoveDesire:
3 — attack, 11 — movement, etc.; and 19 = "the top among all types whatsoever"). The main
technique for its use is to place a new desire guaranteed first: the current
maximum is taken and a large number is added to it.
AddUseSkillDesire( myself.sm, @s_devastated_recall, @ST_HEAL, @AMT_MOVE_TO_TARGET,
( GetTopDesireValue( 3 ) + 10000000000 ) );
Here 3 is the "attack" type: the weight of the top attack desire is taken and a skill is placed with
priority "the current maximum plus ten billion", that is, it will be fulfilled
before everything else.
Signature
GetTopDesireValue( int nDesireType )Parameters
nDesireType (int) — the desire type code whose top weight is to be obtained (for example 3 — attack, 11 — movement, 19 — the top among all types)
Example (illustrative):
GetTopDesireValue( nDesireType );RemoveAttackDesireNPC🟢 high
Removes the desire to hit exactly one specified (by identifier) target, without touching
all the other behavior.
RemoveAttackDesire(attacker.id);
Signature
RemoveAttackDesire( int nTargetObjectId )Parameters
nTargetObjectId (int) — the identifier of the target whose "hit" desire is to be removedUsage example
if ( myself.top_desire_target.is_pc == 0 ) {
RemoveAttackDesire( myself.boss.id );
}RemoveAllAttackDesireNPC🟢 high
Removes all combat desires at once, but leaves the peaceful ones — movement, following, and
the rest. This is how it differs from RemoveAllDesire, which erases absolutely everything.
Signature
RemoveAllAttackDesire( )Parameters
(none — the function is called without arguments)Usage example
if ( myself.p_state != 3 && myself.p_state != 10 ) {
RemoveAllAttackDesire( );
}RemoveAbsoluteDesireNPC🟢 high
There are special desires with an absolute, unoverridable priority. This function
removes such a desire. It returns something as a number, but the meaning of the return is not yet
established.
Signature
RemoveAbsoluteDesire( )Parameters
(none — the function is called without arguments)Example
RemoveAbsoluteDesire();ReportDesireNPC🟢 high
Appears to be a debug function that reports (writes to the log) the current
contents of the desire queue. There are no live calls in the scripts, so it is classed under
questions.
Signature
ReportDesire( )Parameters
(none — the function is called without arguments)Example
ReportDesire( );AGGRO AND HATE LIST (Hate / Aggro)
11 functionsAddHateInfoNPC🟢 high
Changes the hate of the specified creature (CSharedCreatureData) by the given amount and creates
a record in the hate list if one did not exist yet. The amount is usually computed as a weight multiplied
by an event factor (damage, skill use, helping an ally); it can also be negative when
hate needs to be reduced. Per the L2NPC decompile (CNPC::AddHateInfo → HateInfoList::Add_46B410) the third
argument is stored in the record field HateInfo.m_nMapId (map id; always 0 in scripts), and the fourth
and fifth are named modes from manual_pch controlling the addition of a new record and the update
of an existing one. Returns nothing.
Signature
AddHateInfo( CSharedCreatureData c, int nHateValue, int nMapId, int nAddMode, int nUpdateMode )Parameters
c (CSharedCreatureData) — whose hate to change.
nHateValue (int) — amount of the hate change (can be negative).
nMapId (int) — map id in the hate record (HateInfo.m_nMapId); always 0 in the calls.
nAddMode (int) — mode for adding a NEW target (manual_pch):
@AHI_ADD_VALUE (1) — add the record even when the list is full;
@AHI_SET_VALUE (0) — respect the list capacity.
nUpdateMode (int) — mode for an ALREADY existing target (manual_pch):
@AHI_DEL_UPDATE (1) — add the amount to the current hate (accumulate);
@AHI_IGNORE (0) — replace the value, no accumulation.Example
AddHateInfo( c0, 300, 0, 1, 1 );Usage example
if ( creature.is_pc != 0 || IsInCategory( @summon_npc_group, creature.class_id ) ) {
AddHateInfo( creature, ( 7 * 100 ), 0, 1, 1 );
}GetMaxHateInfoNPC🟢 high
Returns the CHateInfo record with the greatest hate — the NPC's main target. The single argument from
manual_pch is not a "rank" but an indication of which metric to search the maximum by. The target is used
via the creature field of the obtained record.
Signature
GetMaxHateInfo( int nValueType )Parameters
nValueType (int) — which metric to search the maximum by (manual_pch):
@GMXHI_HATE_VALUE (0) — by permanent hate (the usual variant);
@GMXHI_TEMP_VALUE (1) — by the temporary value.Example
h0 = GetMaxHateInfo(0);Usage example
h0 = GetMaxHateInfo(0);
if (IsNullHateInfo(h0) == @FALSE)
{
if (IsNullCreature(h0.creature) == @FALSE)
{
MakeAttackEvent(h0.creature, 100, 0);
}
}GetHateInfoCountNPC🟢 high
Returns the number of records in the hate list, no arguments. A result equal to zero means the NPC currently hates no one (no aggro); such a check is a common way to detect the absence of aggro before starting combat logic or to determine that we are facing the first aggressor.
Signature
GetHateInfoCount( )Parameters
(none — the function is called without arguments)Example
i0 = GetHateInfoCount();
i1 = GetHateInfoCount();
i10 = GetHateInfoCount();Usage example
if ( GetHateInfoCount( ) == 0 && i0 == 1 ) {
AddHateInfo( creature, 300, 0, 1, 1 );
} else {
AddHateInfo( creature, 100, 0, 1, 1 );
}GetHateInfoByCreatureNPC🟢 high
Returns the CHateInfo hate record for a specific creature (CSharedCreatureData), to find out whether it is in the list and how much it is hated. The result is validated via IsNullHateInfo.
Signature
GetHateInfoByCreature( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — which creature to look up the record by.Example
h0 = GetHateInfoByCreature(c0);Usage example
h0 = GetHateInfoByCreature( speller );
if ( IsNullHateInfo( h0 ) == 1 ) {
AddHateInfo( speller, 1, 0, 1, 1 );
}GetHateInfoByIndexNPC🟢 high
Returns the CHateInfo record by its ordinal position (nIndex) in the hate list. Used to iterate over all targets by their positions.
Signature
GetHateInfoByIndex( int nIndex )Parameters
nIndex (int) — ordinal position (index) of the record in the hate list.Example
h1 = GetHateInfoByIndex(i1);Usage example
h0 = GetHateInfoByIndex( i0 );
if ( IsNullCreature( h0.creature ) == 0 && IsInCategory( @tanker_group, h0.creature.occupation ) != 1 && Maker_GetNpcCount( ) < 100 && DistFromMe( h0.creature ) <= 8000 ) {
CreateOnePrivateEx( @valakas_lavasaurus, "ai_boss07_cannon", 0, 0, FloatToInt( h0.creature.x ) + Rand( 100 ), FloatToInt( h0.creature.y ) + Rand( 100 ), FloatToInt( h0.creature.z ), 0, h0.creature.id, 0, 0 );
}GetNthHateInfoNPC🟢 high
Returns the n-th CHateInfo record taking the sort criterion and traversal direction into account. The first argument sets the sort criterion (by hate value, ascending; other values are not implemented by the engine), the second — the ordinal number of the record in the sorted list, the third — the traversal direction: from the beginning or from the end of the list (for example, to take the most hated one when sorted ascending).
Signature
GetNthHateInfo( int nSortType, int nIndex, int nDirect )Parameters
nSortType (int) — criterion for sorting the hate list before selection (for example, by hate value)
nIndex (int) — ordinal number of the record in the sorted list
nDirect (int) — traversal direction: from the beginning or from the end of the listExample
h0 = GetNthHateInfo(@GNHI_HATE_VALUE, Rand(9) + 1, @GNHI_ORDER_DOWN);Usage example
h0 = GetNthHateInfo(@GNHI_HATE_VALUE, Rand(9) + 1, @GNHI_ORDER_DOWN);
if (IsNullHateInfo(h0) == @FALSE)
{
if (IsNullCreature(h0.creature) == @FALSE)
{
AddUseSkillDesire(h0.creature, Death_Clack, @ST_ATTACK, @AMT_MOVE_TO_TARGET, 10000000);
}
}GetAvgHateValueNPC🟢 high
Returns the average hate across the whole list, no arguments. Useful for mass-reset or normalization logic — for example, to add hate to everyone relative to the average.
Signature
GetAvgHateValue( )Parameters
(none — the function is called without arguments)Example
GetAvgHateValue( );RemoveHateInfoByCreatureNPC🟢 high
Removes the specified creature (CSharedCreatureData) from the hate list — the NPC "forgets" this target. Used when resetting aggro on a specific player, for example after a teleport, death or leaving the zone. Returns nothing.
Signature
RemoveHateInfoByCreature( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — who to remove from the hate list.Example
RemoveHateInfoByCreature(c0);Usage example
if ( IsNullCreature( c0 ) == 0 && DistFromMe( c0 ) > 12000 ) {
RemoveHateInfoByCreature( c0 );
}RemoveAllHateInfoIFNPC🟢 high
Removes from the hate list all records matching a given condition. The condition is specified by a named constant from [manual_pch]: remove invalid (dead or vanished) targets, clear the entire list, remove those who moved farther than a given distance, or those whose hate is below a threshold. For conditions with a number, the second argument specifies the distance or hate threshold itself; for the "all" and "invalid" conditions it is zero. Returns nothing.
Signature
RemoveAllHateInfoIF( int nCondition, int nThreshold )Parameters
nCondition (int) — removal condition
Constants from [manual_pch] are used:
@COND_ALL (0) — all records of the list
@COND_IS_INVALID (1) — invalid records (target is invalid/gone)
@COND_HAS_HATE_LESS_THAN (2) — records with hate below the given threshold
@COND_IS_FAR_AWAY (3) — records of targets that are too far away
nThreshold (int) — threshold: distance (for @COND_IS_FAR_AWAY) or hate value
(for @COND_HAS_HATE_LESS_THAN); equals 0 for @COND_ALL / @COND_IS_INVALID.Example
RemoveAllHateInfoIF(@COND_ALL, 0);Usage example
if ( ( creature.level + 15 ) < myself.sm.level ) {
RemoveAllHateInfoIF( 0, 0 );
if ( creature.is_pc != 0 || IsInCategory( @summon_npc_group, creature.class_id ) ) {
AddHateInfo( creature, ( 7 * 100 ), 0, 1, 1 );
}
}SetMaxHateListSizeNPC🟢 high
Sets the maximum size of the hate list — how many targets the NPC remembers at once. Takes the maximum number of records; usually configured at NPC initialization. Returns nothing.
Signature
SetMaxHateListSize( int nMaxSize )Parameters
nMaxSize (int) — maximum number of records (targets) the NPC remembers in the hate list.Example
SetMaxHateListSize(1);SetHateInfoListIndexNPC🟢 high
Sets the current index-cursor in the hate list for sequential traversal of records. Takes the cursor position; the exact meaning is not fully confirmed. Returns nothing.
Signature
SetHateInfoListIndex( int nIndex )Parameters
nIndex (int) — current cursor position in the hate list for sequential traversalExample
SetHateInfoListIndex( 1 );Usage example
for( i0 = 0; i0 < 4; ++i0 ) {
SetHateInfoListIndex( i0 );
SetMaxHateListSize( 200 );
}NPC behavior & parameters (Behavior / Params)
35 functionsAllocCodeInfoListGLOBAL🟢 high
Creates an empty accumulator list (CCodeInfoList) for the random-selection mechanism: options are put into it via SetInfo, then RandomSelectOne pulls one at random. Used in the logic of picking a random target/line/branch.
Signature
AllocCodeInfoList( )Parameters
(none — the function is called without arguments)Example
always_list = AllocCodeInfoList( );
random1_list = AllocCodeInfoList( );SetInfoGLOBAL🟢 high
Adds to the accumulator list (created by AllocCodeInfoList) a pair "code + creature": nCode is the option identifier, cCreature is the associated creature (for example, a target candidate).
Signature
SetInfo( int nCode, CSharedCreatureData cCreature )Parameters
nCode (int) — the code identifier of the option in the accumulator list
cCreature (CSharedCreatureData) — the creature associated with the codeExample
random1_list.SetInfo( 0, target );RandomSelectOneGLOBAL🟢 high
Randomly picks and returns one element from the accumulator list previously filled via SetInfo. Completes the pairing AllocCodeInfoList -> SetInfo -> RandomSelectOne.
Signature
RandomSelectOne( )Parameters
(none — the function is called without arguments)Example
code_info = random1_list.RandomSelectOne( );GetNPCFromIDGLOBAL🟢 high
Returns an NPC by its object-id (nObjectId), which is often stored in param*/variables. The result is checked via IsNull* before accessing fields.
Signature
GetNPCFromID( int nObjectId )Parameters
nObjectId (int) — the object-id of the NPC being searchedExample
npc0 = GetNPCFromID( myself.sm.param3 );
npc0 = GetNPCFromID( c0.id );
npc0 = GetNPCFromID( myself.sm.param1 );Usage example
npc0 = GetNPCFromID( myself.sm.param3 );
if ( IsNull( npc0 ) == 0 ) {
npc0.i_quest0 = 0;
}IncreaseAPGLOBAL🟢 high
Credits the player c with nAP arena/fame points (AP).
Signature
IncreaseAP( CSharedCreatureData c, int nAP )Parameters
c (CSharedCreatureData) — the player credited with arena/fame points
nAP (int) — the number of AP points creditedExample
IncreaseAP(talker, 6);
IncreaseAP( talker, 5 );
IncreaseAP( talker, 8 );
IncreaseAP( talker, 10 );SetNpcParamGLOBAL🟢 high
Sets a runtime parameter of the NPC c (a vital/combat coefficient): nVcpType is the type (@VCP_*), dValue is the value (float).
Signature
SetNpcParam( CSharedCreatureData cCreature, int nVcpType, float dValue )Parameters
cCreature (CSharedCreatureData) — the NPC whose runtime parameter is set
nVcpType (int) — the choice of the parameter type being set
a value from the @VCP_* family — creature properties (HP, MP, stats, attack/defense, etc.); the full list is in [manual_pch]
dValue (float) — the new parameter valueExample
SetNpcParam( myself.sm, @VCP_HP, myself.sm.max_hp * 0.2 );Usage example
if ( myself.sm.flag == @SCE_FRINTESSA_SPAWN_DEMON_FINAL ) {
SetNpcParam( myself.sm, @VCP_HP, myself.sm.max_hp * 0.2 );
return;
}GetValueGLOBAL🟢 high
Reads an atomic value (a counter with thread-safe access, CAtomicValue).
Signature
GetValue( )Parameters
(none — the function is called without arguments)Example
if ( myself.av_quest0.GetValue( ) != 1 ) {Usage example
if ( myself.av_quest0.GetValue( ) != 1 ) {
myself.i_quest0 = 0;
}GetPchValueGLOBAL🟢 high
Resolves a pch-constant's value by its name string sName (dynamic access to the @-dictionary).
Signature
GetPchValue( string name )Parameters
name (string) — the name of the `@`-constant whose value is to be obtainedExample
if ( GetPchValue( "client_hf" ) == 1 ) {Usage example
if ( GetPchValue( "client_hf" ) == 1 ) {
ShowBuySell( talker, SellList0, BuyList0, -50 );
} else {
Sell( talker, SellList0, ShopName, fnBuy, _blank, _blank );
}IsSameStringGLOBAL🟢 high
Compares two strings s1 and s2: returns 1 if equal, otherwise 0.
Signature
IsSameString( string s1, string s2 )Parameters
s1 (string) — the first string being compared
s2 (string) — the second string being comparedExample
if ( IsSameString( DoorName, "altar_door_controller_basic_default" ) == 0 ) {Usage example
if ( IsSameString( DoorName, "altar_door_controller_basic_default" ) == 0 ) {
Castle_GateOpenClose2( DoorName, 0 );
}IntToFStrGLOBAL🟢 high
Converts a number n to a string for substitution into phrases (FString).
Signature
IntToFStr( int64 nNum )Parameters
nNum (int64) — the number converted to a string for substitution into phrasesExample
ChangeFStrNickName(myself.sm, 1801100, IntToFStr(i1));GetCurrentTickNPC🟢 high
Returns the current server time in ticks (milliseconds of the server timer). Used for measuring intervals: remember the tick, later compare the difference (cooldowns, phase timings, dialog anti-spam).
Signature
GetCurrentTick( )Parameters
(none — the function is called without arguments)Example
if ( ( GetCurrentTick( ) - talker.quest_last_reward_time ) > 1 ) {Usage example
i0 = GetCurrentTick( );
if ( i0 > ( myself.i_quest1 + 5 ) ) {
if ( IsNullCreature( myself.top_desire_target ) == 0 ) {
if ( Skill_GetConsumeMP( Hold ) < myself.sm.mp && Skill_GetConsumeHP( Hold ) < myself.sm.hp && Skill_InReuseDelay( Hold ) == 0 ) {
AddUseSkillDesire( myself.top_desire_target, Hold, @ST_ATTACK, @AMT_MOVE_TO_TARGET, 1000000 );
}
}
}GetTickNPC🟢 high
Same as GetCurrentTick: returns the current server time in ticks for measuring intervals between events.
Signature
GetTick( )Parameters
(none — the function is called without arguments)Example
myself.i_ai1 = GetTick( );Usage example
if ( ( GetTick( ) - myself.i_ai1 ) > ( ( 5 * 60 ) * 1000 ) ) {
myself.i_ai3 = 0;
BroadcastScriptEvent( 1000, 0, 300 );
}GetLastAttackerNPC🟢 high
Returns the handle of the creature that last dealt damage to this NPC (for retaliation reactions). Check the result via IsNull* before accessing its fields.
Signature
GetLastAttacker( )Parameters
(none — the function is called without arguments)Example
c1 = GetLastAttacker( );
c0 = GetLastAttacker( );
target = GetLastAttacker( );
c2 = GetLastAttacker();Usage example
c1 = GetLastAttacker( );
if ( c1.master ) { c1 = c1.master; }GetMasterUserNPC🟢 high
For a summoned/summon NPC, returns the handle of the owning player. Check the result via IsNull* before accessing its fields.
Signature
GetMasterUser( )Parameters
(none — the function is called without arguments)
Example: no direct calls in our scripts.LookNeighborNPC🟢 high
Makes the NPC "look around": triggers neighbor perception events within radius nRadius (often before searching for targets).
Signature
LookNeighbor( int nRadius )Parameters
nRadius (int) — radius for looking around at neighbors (in calls, e.g., 300).Example
if ( AttackLowLevel == 1 ) { LookNeighbor( 300 ); }ChangeMoveTypeNPC🟢 high
Changes the NPC's movement manner: nMoveType = @MT_SLOW (0, walking) or @MT_FAST (1, running).
Signature
ChangeMoveType( int nMoveType )Parameters
nMoveType (int) — way of moving to the target when executing a desire
Constants from [manual_pch] are used:
@AMT_STAND (0) — attack in place, without closing in
@AMT_MOVE_TO_TARGET (1) — close in on the target and attack (pursue)Example
ChangeMoveType(@MT_FAST);
ChangeMoveType( 1 );
ChangeMoveType( 0 );
ChangeMoveType(@MT_SLOW);Usage example
if ( IsNullCreature( c0 ) == 0 ) {
ChangeMoveType( 1 );
AddMoveToDesire( FloatToInt( c0.x ), FloatToInt( c0.y ), FloatToInt( c0.z ), 10000000 );
}ChangeMoveType2NPC🟢 high
Same as ChangeMoveType, plus bForce: when 1, the change is applied forcibly, bypassing checks.
Signature
ChangeMoveType2( int nMoveType, int bForce )Parameters
nMoveType (int) — way of moving to the target when executing a desire
Constants from [manual_pch] are used:
@AMT_STAND (0) — attack in place, without closing in
@AMT_MOVE_TO_TARGET (1) — close in on the target and attack (pursue)
bForce (int) — flag for forced change bypassing checks (1 — forced)Example
ChangeMoveType2(@MT_FAST, 1);
ChangeMoveType2( 0, 1 );
ChangeMoveType2( 1, 1 );
ChangeMoveType2(@MT_SLOW, 1);FixMoveTypeNPC🟢 high
Locks or unlocks the NPC's current movement type: bBlock = 1 forbids changing it, 0 allows it.
Signature
FixMoveType( int bBlock )Parameters
bBlock (int) — lock flag: 1 — forbid changing the movement type, 0 — allowExample
FixMoveType(1);StopMoveNPC🟢 high
Immediately stops the NPC's movement.
Signature
StopMove( )Parameters
(none — the function is called without arguments)Example
StopMove( );Usage example
if ( myself.sm.in_peacezone != 0 ) {
StopMove( );
RemoveAllDesire( );
RemoveAllHateInfoIF( 0, 0 );
InstantTeleport( myself.sm, myself.start_x, myself.start_y, myself.start_z );
return;
}SetVisibleNPC🟢 high
Shows or hides the NPC: bVisible = @FALSE (0) makes it invisible, @TRUE (1) — visible.
Signature
SetVisible( int bVisible )Parameters
bVisible (int) — NPC visibility: @TRUE (1) — show, @FALSE (0) — hide.Example
SetVisible(@FALSE);Usage example
if ( GetSSQStatus( ) != @SS_SEAL_EFFECT && GetSSQStatus( ) != @SS_ACCOUNTING ) {
SetVisible( 0 );
}ChangeNPCStateNPC🟢 high
Changes the visual state/animation mode of NPC c to nState.
Signature
ChangeNPCState( CSharedCreatureData pCreatureShared, int nState )Parameters
pCreatureShared (CSharedCreatureData) — the creature itself whose visual state is changed (usually `myself.sm`)
nState (int) — number of the new animation state/display modeExample
ChangeNPCState(myself.sm, 1);Usage example
if ( timer_id == OFF_TIMER ) {
ChangeNPCState( myself.sm, 2 );
}ChangeStatusNPC🟢 high
Changes the NPC's displayed status — name visibility and whether it can be targeted.
Signature
ChangeStatus( int nStatus )Parameters
nStatus (int) — new NPC status (manual_pch):
@NAME_INVISIBLE (0) — hide the name; @NAME_VISIBLE (1) — show the name;
@TARGET_DISABLE (2) — forbid targeting; @TARGET_ENABLE (3) — allow targeting.Example
ChangeStatus(@TARGET_DISABLE);ChangeDirNPC🟢 high
Turns the NPC toward target nTargetId at angle nAngle; the first argument is the creature itself (usually myself.sm).
Signature
ChangeDir( CSharedCreatureData pCreatureShared, int nTargetId, int nAngle )Parameters
pCreatureShared (CSharedCreatureData) — the creature itself being turned (usually `myself.sm`)
nTargetId (int) — identifier of the target toward which the NPC is turned
nAngle (int) — turn angle relative to the targetExample
ChangeDir(myself.sm, c0.id, 0);Usage example
if ( FloatToInt( myself.sm.x ) == myself.start_x && myself.start_y == FloatToInt( myself.sm.y ) ) {
ChangeDir( myself.sm, 0, direction );
} else {
InstantTeleport( myself.sm, myself.start_x, myself.start_y, myself.start_z );
}SuicideNPC🟢 high
The NPC instantly "dies" without specifying a culprit.
Signature
Suicide( )Parameters
(none — the function is called without arguments)Example
Suicide( );Usage example
if ( skill_name_id == SelfExplosion ) {
Suicide( );
}SuicideByNPC🟢 high
Same as Suicide, but specifies the culprit c (for logging/drop).
Signature
SuicideBy( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — creature responsible for the death (recorded in the log/counted for drop)Example
SuicideBy( myself.c_ai0 );PlayAnimationNPC🟢 high
Plays an NPC animation/social action for surrounding players. Per the L2NPC decompile (CNPC::PlayAnimation_49348C)
both numbers go to clients in a packet with opcode 144 "cddd": the first is the animation number, the second is the
display radius (in scripts the variable is called FreewayPlayAniRange; in calls 600, 5000).
Signature
PlayAnimation( int nAnimId, int nRange )Parameters
nAnimId (int) — number/identifier of the animation or social action to play (in calls 0..4).
nRange (int) — radius for showing the animation to those around (in calls 600, 5000).Example
PlayAnimation(script_event_arg3, FreewayPlayAniRange);Usage example
if (timer_id == PHASE_ANI) {
PlayAnimation(4, 600);
}GetMyDirectionNPC🟢 high
Returns the NPC's current heading (facing direction); units are the same as GetDirection.
Signature
GetMyDirection( )Parameters
(none — the function is called without arguments)Example
CreateOnePrivateEx(corpse, ai_corpse, 0, 0, FloatToInt(myself.sm.x), FloatToInt(myself.sm.y), FloatToInt(myself.sm.z), GetMyDirection(), GetIndexFromCreature(myself.sm), GetIndexFromCreature(myself.c_ai1), 0);IsInThisTerritoryNPC🟢 high
Returns 1 if the NPC is within the named territory sName, otherwise 0.
Signature
IsInThisTerritory( string sName )Parameters
sName (string) — name of the named territory to check (e.g. "25_15_frintessa_NoCharge01").Example
if ( IsInThisTerritory( "25_15_frintessa_NoCharge01" ) == 1 ) {Usage example
if ( IsInThisTerritory( "25_15_frintessa_NoCharge01" ) == 1 ) {
if ( IsNullCreature( c2 ) == 0 ) {
AddUseSkillDesire( c2, DashAllVer1, @ST_ATTACK, @AMT_MOVE_TO_TARGET, 10000 );
}
}IsInCombatModeNPC🟢 high
Returns whether the creature c is in combat mode (compared with @FALSE/@TRUE).
Signature
IsInCombatMode( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature whose combat mode is checkedExample
if (i0 > 15 && IsInCombatMode(myself.sm) == @FALSE)Usage example
if ( IsInCombatMode( myself.sm ) == 0 ) {
return;
}IsBossNPC🟢 high
Returns whether the NPC itself is a boss (compared with @FALSE/@TRUE).
Signature
IsBoss( )Parameters
(none — the function is called without arguments)Example
if (IsBoss() == @FALSE)Usage example
if ( IsBoss( ) == 0 ) {
AddAttackDesire( speller, @AMT_MOVE_TO_TARGET, desire );
}IsMyBossAliveNPC🟢 high
For a minion returns whether its boss is alive (compared with @FALSE/@TRUE).
Signature
IsMyBossAlive( )Parameters
(none — the function is called without arguments)Example
if (IsMyBossAlive() == @FALSE)Usage example
if ( IsMyBossAlive( ) == 0 ) {
Despawn( );
}GetIdleTimeNPC🟢 high
Returns how long the creature c has been idle (without actions).
Signature
GetIdleTime( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the creature whose idle time is requestedExample
if (creature.is_pc == 1 && GetIdleTime(creature) > 60)Usage example
if (creature.is_pc == 1 && GetIdleTime(creature) > 60)
{
InstantTeleport(creature, 35118, 147753, -3528);
}SetDieEventNPC🟢 high
Enables/disables the broadcast of a creature's death event to the surroundings. Per the L2NPC decompile
(CNPC::SetDieEvent_496C38) the second argument is a boolean flag (stored as c!=0), the third — the broadcast
radius, limited by the engine to ≤ 2048 (otherwise the log "Too long distance to broadcast").
Signature
SetDieEvent( CSharedCreatureData c, int bEnable, int nBroadcastDist )Parameters
c (CSharedCreatureData) — the creature for which the death-event broadcast is configured.
bEnable (int) — enable (1) or disable (0) the death-event broadcast.
nBroadcastDist (int) — the event broadcast radius, ≤ 2048 (in calls 2000; more — rejected with an error to the log).Example
SetDieEvent( creature, 1, 2000 );
SetDieEvent( target, 1, 2000 );
SetDieEvent(attacker, 1, 2000);Usage example
if ( IsNullCreature( creature ) == 0 && creature.is_pc == 1 ) {
SetDieEvent( creature, 1, 2000 );
}IncrementParamNPC🟢 high
Changes the character c's parameter by the amount nValue. nParam — @PARAM_*: EXP=0, SP=1, INT=2, STR=3, CON=4, MEN=5, DEX=6, WIT=7, LEVEL=8, PKCOUNT=9.
Signature
IncrementParam( CSharedCreatureData c, int nParam, int64 nValue )Parameters
c (CSharedCreatureData) — the character whose parameter is changed.
nParam (int) — the choice of the character parameter being changed
Constants from [manual_pch] are used:
@PARAM_EXP (0) — experience (EXP)
@PARAM_SP (1) — skill points (SP)
@PARAM_INT (2) — Intelligence (INT)
@PARAM_STR (3) — Strength (STR)
@PARAM_CON (4) — Constitution (CON)
@PARAM_MEN (5) — Mentality (MEN)
@PARAM_DEX (6) — Dexterity (DEX)
@PARAM_WIT (7) — Wit (WIT)
@PARAM_LEVEL (8) — level
@PARAM_PKCOUNT (9) — the player kill counter (PK)
@PARAM_KARMA (13) — karma
@PARAM_SKILL_MULTIPLIER (65536) — the skill multiplier
nValue (int64) — the amount of the parameter change (signed).Example
IncrementParam( talker, @PARAM_EXP, 2299404 * QuestExpRate );Usage example
if ( DeleteItem1( talker, @adena, 650000 ) ) {
IncrementParam( talker, @PARAM_SP, -30000 );
PledgeLevelUp( talker, 1 );
}GetAIParameterNPC🟢 high
Reads the creature c's AI parameter by its type nType.
Signature
GetAIParameter( CSharedCreatureData c, int Type )Parameters
c (CSharedCreatureData) — the creature whose AI parameter is read
Type (int) — which inventory metric to return
Constants from [manual_pch] are used:
@IPT_CURRENT_SLOT_COUNT (0) — inventory slots currently occupied
@IPT_MAX_SLOT_COUNT (1) — maximum inventory slots
@IPT_CURRENT_WEIGHT (2) — current carried weight
@IPT_MAX_CARRY_WEIGHT (3) — maximum carry weight
@IPT_CURRENT_QUEST_SCOUNT (4) — quest slots currently occupied
@IPT_MAX_QUEST_SCOUNT (5) — maximum quest slotsExample
i0 = GetAIParameter(myself.c_ai0, 3);COMBAT, BEHAVIOR, WORLD OBJECTS AND UI MESSAGES (Combat / WorldTrap / AirShip / UI)
40 functionsSendUIEventGLOBAL🟢 high
Sends an interface event nMode to the player talker (CSharedCreatureData) with numeric parameters nArg1, nArg2 and strings sArg3..10; used for time counters, progress bars, etc. A method of the global object (CGlobalObject), no return value.
Signature
SendUIEvent( CSharedCreatureData cCreature, int nMode, int nArg1, int nArg2, string sArg1, string sArg2, string sArg3, string sArg4, string sArg5, string sArg6 )Parameters
cCreature (CSharedCreatureData) — the recipient player of the interface event
nMode (int) — the mode (type) of the interface event
nArg1 (int) — numeric parameter 1 of the event
nArg2 (int) — numeric parameter 2 of the event
sArg1 (string) — string parameter 1
sArg2 (string) — string parameter 2
sArg3 (string) — string parameter 3
sArg4 (string) — string parameter 4
sArg5 (string) — string parameter 5
sArg6 (string) — string parameter 6Example
SendUIEvent( talker, 0, 0, 0, "0", "0", "0", "", "0", "0" );Usage example
if ( talker.flag == 125 ) {
SendUIEvent( talker, 0, 0, 0, "0", "60", "0", "Elapsed", "0", "0" );
}SendUIEventFStrGLOBAL🟢 high
The same as SendUIEvent, but with FString-formatting support (nFstringId — the phrase ID for insertion and additional strings sArg11..15). A method of the global object (CGlobalObject), no return value.
Signature
SendUIEventFStr( CSharedCreatureData cCreature, int nArg1, int nArg2, int nArg3, string pStr1, string pStr2, string pStr3, string pStr4, string pStr5, int nArg4, string pStr6, string pStr7, string pStr8, string pStr9, string pStr10 )Parameters
cCreature (CSharedCreatureData) — the recipient player of the interface event
nArg1 (int) — the mode (type) of the interface event
nArg2 (int) — numeric parameter 1 of the event
nArg3 (int) — numeric parameter 2 of the event
pStr1 (string) — string parameter 1
pStr2 (string) — string parameter 2
pStr3 (string) — string parameter 3
pStr4 (string) — string parameter 4
pStr5 (string) — string parameter 5
nArg4 (int) — the identifier of the FString phrase for insertion
pStr6 (string) — additional string parameter 1
pStr7 (string) — additional string parameter 2
pStr8 (string) — additional string parameter 3
pStr9 (string) — additional string parameter 4
pStr10 (string) — additional string parameter 5Example
SendUIEventFStr(target, 2, 0, 0, p_sNoTimer, IntToStr(myself.av_ai0.GetValue()), IntToStr(inst_duration), p_sPercent, "0", p_iTitleUI, _blank, _blank, _blank, _blank, _blank);Usage example
if (myself.sm.flag == 2) {
SendUIEventFStr(target, 2, 0, 0, p_sNoTimer, IntToStr(myself.av_ai0.GetValue()), IntToStr(inst_duration), p_sPercent, "0", p_iTitleUI, _blank, _blank, _blank, _blank, _blank);
} else {
SendUIEventFStr(target, 5, 0, 0, p_sNoTimer, IntToStr(myself.av_ai0.GetValue()), IntToStr(inst_duration), p_sPercent, "0", p_iTitleUI, _blank, _blank, _blank, _blank, _blank);
}ShowMsgInTerritoryGLOBAL🟢 high
Announces the system message nSysMsgId to all players in the named territory sAnnounceArea with the zone object nZoneObjId. A method of the global object (CGlobalObject), no return value.
Signature
ShowMsgInTerritory( int nInZoneObjectId, string pwsAnnounceAreaName, int nSysMsgId )Parameters
nInZoneObjectId (int) — the identifier of the zone object in which the message is announced
pwsAnnounceAreaName (string) — the name of the territory for the announcement
nSysMsgId (int) — the identifier of the system messageExample
ShowMsgInTerritory(0, AnnounceZone, systemmsgId);
ShowMsgInTerritory( 0, AnonceZone, 8377 );
ShowMsgInTerritory(0, AnonceZone, 8380);
ShowMsgInTerritory(0, AnonceZone, 8381);ShowFStrMsgInTerritory2GLOBAL🟢 high
The same as ShowMsgInTerritory, but with FString-formatting by nFstringId and substitution of up to 5 strings sStr1..5. A method of the global object (CGlobalObject), no return value.
Signature
ShowFStrMsgInTerritory2( int nInZoneObjectId, string pwsAnnounceAreaName, int nFstringId, string Str1, string Str2, string Str3, string Str4, string Str5 )Parameters
nInZoneObjectId (int) — the identifier of the zone object in which the message is announced
pwsAnnounceAreaName (string) — the name of the territory for the announcement
nFstringId (int) — the identifier of the FString phrase for formatting
Str1 (string) — substitution string 1
Str2 (string) — substitution string 2
Str3 (string) — substitution string 3
Str4 (string) — substitution string 4
Str5 (string) — substitution string 5Example
ShowFStrMsgInTerritory2(0, "25_15_frintezza_announce01", 1010643, IntToStr(myself.av_ai1.GetValue()), _blank, _blank, _blank, _blank);GetAcquireExpRateBossGLOBAL🟢 high
Returns the experience multiplier for a character of level nLevel when killing a boss (usually less than 1 for high levels). A method of the global object (CGlobalObject), returns a float.
Signature
GetAcquireExpRateBoss( int nLevel )Parameters
nLevel (int) — the character level for which the experience multiplier from a boss is returnedExample
i0 = FloatToInt(InstanceBossGetExp * GetAcquireExpRateBoss(target.level) * f0);AddPCSocialGLOBAL🟢 high
Performs the social action nSocialAction (dance, greeting, war cry, etc.) for the character with index nUserIndex. A method of the global object (CGlobalObject), no return value.
Signature
AddPCSocial( int nUserIndex, int nSocialAction )Parameters
nUserIndex (int) — the index of the performing character. Taken from GetIndexFromCreature(talker).
nSocialAction (int) — the type of social gesture. This is a @SAT_* constant (set in manual_pch);
a raw number is equivalent to the constant (in calls 3 == @SAT_VICTORY):
in code number smysl
@SAT_GREET 2 greeting
@SAT_VICTORY 3 victory gesture
@SAT_ADVANCE 4 "advance"
@SAT_NO 5 "no"
@SAT_YES 6 "yes"
@SAT_BOW 7 bow
@SAT_UNAWARE 8 bewilderment
@SAT_WAITINGA 9 waiting
@SAT_LAUGH 10 laugh
@SAT_APPLAUS 11 applause
@SAT_DANCE 12 dance
@SAT_SAD 13 sadness
@SAT_LEVEL_UP 15 level-up effect
@SAT_HERO 16 hero effect
@SAT_CURSED_WEAPON_LEVEL_UP 17 cursed weapon level-up
Actually found in scripts: @SAT_VICTORY/3 (widely), @SAT_BOW/7. The other values are
from the general list of gestures, available via the same function.Example
AddPCSocial( GetIndexFromCreature(talker), @SAT_VICTORY ); // the player plays the victory gesture (same as 3)CanAttackNPC🟢 high
Checks whether the NPC can attack the creature target (CSharedCreatureData); returns 1 if the attack is possible, 0 if it is blocked (immunity, peace zone, ghost, etc.). Creature method (CNPC).
Signature
CanAttack( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the attack target for which the NPC's ability to attack is checkedExample
if (CanAttack(myself.top_desire_target) == @TRUE)Usage example
if ( CanAttack( attacker ) == 1 ) {
MakeAttackEvent( attacker, ( damage / 2 ), 0 );
}IsAttackableNPC🟢 high
Checks whether the target (CSharedCreatureData) can be hit — whether it exists on the map, is not hidden, is not in a special state; returns 1 if the target is attackable. Creature method (CNPC).
Signature
IsAttackable( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the target checked for being available to hitExample
if (attacker.is_pc == @FALSE && ((attacker.npc_class_id != 1033609 && attacker.npc_class_id != 1033611 && attacker.npc_class_id != 1033613 && attacker.npc_class_id != 1033615 && attacker.npc_class_id != 1033618 && attacker.npc_class_id != 1033617 && attacker.npc_class_id != 1033798) && (attacker.npc_class_id != 1033620 && attacker.npc_class_id != 1033622 && attacker.npc_class_id != 1033624 && attacker.npc_class_id != 1033626 && attacker.npc_class_id != 1033629 && attacker.npc_class_id != 1033628 && attacker.npc_class_id != 1033799) && (attacker.npc_class_id != 1033631 && attacker.npc_class_id != 1033633 && attacker.npc_class_id != @hayuk_cartia_95_02 && attacker.npc_class_id != @elliyah_cartia_95_02 && attacker.npc_class_id != @elliyah_guard_95_01 && attacker.npc_class_id != @alice_cartia_95_02 && attacker.npc_class_id != @cartia_95_mirror) && attacker.npc_class_id != @soldier_cartia_85_01 && attacker.npc_class_id != @soldier_cartia_90_01 && attacker.npc_class_id != @soldier_cartia_95_01 && attacker.npc_class_id != @prisoner_cartia_85_01 && attacker.npc_class_id != @prisoner_cartia_90_01 && attacker.npc_class_id != @prisoner_cartia_95_01) && IsInCategory(@summon_npc_group, attacker.npc_class_id) == @FALSE && IsAttackable(attacker) == 1)Usage example
if (IsAttackable(myself.sm) == @TRUE)
{
SetAttackable(myself.sm, @FALSE);
}SetAttackableNPC🟢 high
Sets or clears the attackable flag on the creature target (CSharedCreatureData): bFlag @TRUE/1 — attackable, @FALSE/0 — unattackable; usually applied to myself.sm for the NPC itself. Creature method (CNPC), no return value.
Signature
SetAttackable( CSharedCreatureData pCreatureShared, int nAttackable )Parameters
pCreatureShared (CSharedCreatureData) — the creature whose attackable flag is set (usually the NPC itself via `myself.sm`)
nAttackable (int) — flag: `@TRUE`/1 — make attackable, `@FALSE`/0 — remove attackabilityExample
SetAttackable(myself.sm, @FALSE);
SetAttackable(myself.sm, @TRUE);
SetAttackable( myself.sm, 0 );
SetAttackable( myself.sm, 1 );Usage example
if ( attacker.is_pc == @TRUE && skill_name_id == @s_prominence11 ) {
SetAttackable(myself.sm, @FALSE);
Say("Now is NOT Attackable!");
}GetPathfindFailCountNPC🟢 high
Returns the number of consecutive failures when computing the NPC's path; reset to zero on successful movement. Creature method (CNPC), no arguments.
Signature
GetPathfindFailCount( )Parameters
(none — the function is called without arguments)Example
if (GetPathfindFailCount() > 10 && speller == myself.top_desire_target && FloatToInt(myself.sm.hp) != FloatToInt(myself.sm.max_hp)) {Usage example
if (GetPathfindFailCount() > 10 && speller == myself.top_desire_target && FloatToInt(myself.sm.hp) != FloatToInt(myself.sm.max_hp)) {
InstantTeleport(myself.sm, FloatToInt(speller.x), FloatToInt(speller.y), FloatToInt(speller.z));
}GetWayPointDelayNPC🟢 high
Returns the delay time at the route node with index nIndex from the wayPoints array (waypointdelaystype). Creature method (CNPC), returns int.
Signature
GetWayPointDelay( WayPointDelaysType aWayPoints, int nIndex )Parameters
aWayPoints (WayPointDelaysType) — the array of route node (waypoint) delays the value is taken from.
nIndex (int) — the index of the route node whose delay is returned.Example
AddTimerEx( 100001, ( GetWayPointDelay( WayPointDelays, way_point_index ) * 1000 ) );ChangeStopTypeNPC🟢 high
Changes the NPC's behavior when stopped: nType (0 — stands and listens, 1 — active mode), nTimeout — time in milliseconds. Creature method (CNPC), no return value.
Signature
ChangeStopType( int nType, int nTimeout )Parameters
nType (int) — stop behavior type: 0 — stands and listens, 1 — active mode.
nTimeout (int) — duration of the mode, milliseconds (30000 in calls).Example
ChangeStopType(0, 30000);
ChangeStopType(1, 30000);Usage example
if (myself.sm.stop_mode == 1) {
ChangeStopType(0, 30000);
} else {
ChangeStopType(1, 30000);
}GetOverhitBonusNPC🟢 high
Returns the "overhit" coefficient for a creature — how much stronger the last hit on it
was compared to what was needed for it to die. This is a fractional number: 1 means a normal
finishing blow with no excess, and greater than 1 means the creature was finished off with a
surplus (the bigger the excess, the higher the value). In scripts it is compared against
thresholds: > 1 — whether there was an overhit at all, >= 1.2 — whether the overhit was
strong enough to count a bonus or mark. There is a single argument — the creature whose
overhit is checked (usually myself.sm, i.e. the NPC that was killed). Returns a fractional
value (float).
Signature
GetOverhitBonus( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature whose overhit coefficient is checked (usually `myself.sm`).Example
if (GetOverhitBonus(myself.sm) > 1)Usage example
if (GetOverhitBonus(myself.sm) >= 1.200000) {
SetMemoStateEx(last_attacker, 458, 2, GetMemoStateEx(last_attacker, 458, 2) + 1);
}UnequipWeaponNPC🟢 high
Removes the NPC's main weapon; used when changing combat tactics. Creature method (CNPC), no arguments and no return value.
Signature
UnequipWeapon( )Parameters
(none — the function is called without arguments)Example
UnequipWeapon();Usage example
if (timer_id == CHANGE_TIMER) {
UnequipWeapon();
}SetEnchantOfWeaponNPC🟢 high
Sets the enchant level of the NPC's weapon to nEnchantLevel (0, 10, 15, etc.). Creature method (CNPC), no return value.
Signature
SetEnchantOfWeapon( int nEnchantLevel )Parameters
nEnchantLevel (int) — enchant level of the NPC's weapon (0, 10, 15 in calls).Example
SetEnchantOfWeapon( 15 );
SetEnchantOfWeapon( 10 );
SetEnchantOfWeapon( 0 );IsWeaponEquippedInHandNPC🟢 high
Checks whether the creature target (CSharedCreatureData) has a weapon equipped in hand; returns 1 if it does, 0 if unarmed. Creature method (CNPC).
Signature
IsWeaponEquippedInHand( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature checked for having a weapon in handExample
if ( creature.is_pc == @TRUE && IsWeaponEquippedInHand( creature ) == 1 ) {Usage example
if ( creature.is_pc == @TRUE && IsWeaponEquippedInHand( creature ) == 1 ) {
if ( Skill_GetConsumeMP( Skill02_ID ) < myself.sm.mp && Skill_GetConsumeHP( Skill02_ID ) < myself.sm.hp && Skill_InReuseDelay( Skill02_ID ) == 0 ) {
AddUseSkillDesire( creature, Skill02_ID, @ST_ATTACK, @AMT_MOVE_TO_TARGET, 1000000 );
}
myself.c_ai0 = creature;
}SetAbilityItemDropNPC🟢 high
Controls the flag for dropping items when the NPC is killed: nFlag @FALSE/0 — no drop, 1 — drop enabled. Creature method (CNPC), no return value.
Signature
SetAbilityItemDrop( int nCanDrop )Parameters
nCanDrop (int) — item drop flag on kill: `@FALSE`/0 — no drop, 1 — drop enabledExample
SetAbilityItemDrop( 0 );
SetAbilityItemDrop(@FALSE);
SetAbilityItemDrop( 1 );Usage example
if (IsInCategory(@beastfarm_beast, last_attacker.class_id) == 1) {
SetAbilityItemDrop(0);
}IsStackableItemExNPC🟢 high
Checks whether the item with index nItemIndex can be combined into a stack; returns 1 if it is stackable.
Signature
IsStackableItemEx( int nItemIndex )Parameters
nItemIndex (int) — the item index (usually from item_index_list.GetItemIndex) whose stackability is checked.Example
if ( IsStackableItemEx( item_index_list.GetItemIndex( i1 ) ) ) {Usage example
if ( IsStackableItemEx( item_index_list.GetItemIndex( i1 ) ) ) {
AddGetItemDesireEx( item_index_list.GetItemIndex( i1 ), ( 10000 - i1 ) );
}ChangeUserTalkTargetNPC🟢 high
Transfers the NPC's dialog focus to the creature npc (CSharedCreatureData); used in scripts with multiple NPCs to change the speaker. No return value.
Signature
ChangeUserTalkTarget( CSharedCreatureData pCreatureShared )Parameters
pCreatureShared (CSharedCreatureData) — the creature (NPC) the dialog focus is transferred toExample
ChangeUserTalkTarget( creature );
ChangeUserTalkTarget( myself.c_ai0 );
ChangeUserTalkTarget(talker);IsAliveNPC🟢 high
Checks whether the creature (CCreature) is alive; returns 1 if alive, 0 if dead or in spirit form. Built-in method of the CCreature type.
Signature
IsAlive( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature checked for being aliveExample
if ( IsAlive( creature ) == @FALSE || ( creature.is_pc == 0 && IsInCategory( @summon_npc_group, creature.class_id ) == 0 ) ) {Usage example
if ( IsAlive( creature ) == @FALSE || ( creature.is_pc == 0 && IsInCategory( @summon_npc_group, creature.class_id ) == 0 ) ) {
return;
}HotSpotChangeStateNPC🟢 high
Switches the state of an interactive zone (Hotspot) at coordinates (nX, nY, nZ): nState 0, 1, 2 — different states (active, inactive, invisible, etc.). No return value.
Signature
HotSpotChangeState( int nState, int nX, int nY, int nZ )Parameters
nState (int) — new zone state: 0, 1, 2 — active/inactive/invisible, etc.
nX (int) — X coordinate of the interactive zone
nY (int) — Y coordinate of the interactive zone
nZ (int) — Z coordinate of the interactive zoneExample
HotSpotChangeState(0, 90067, -110007, 1032);ChangeZoneInfoNPC🟢 high
Marks a specific creature with a zone mode — sets or clears an attribute on it
tied to a special zone (in calls this is @ZONEINFO_FREYA, the Freya battle zone). The first argument
is who it is set on (in scripts, a player from the hate list or an instant zone participant), the second is which
particular zone attribute, the third is the value of that attribute (1 or 2 in calls). By usage context the
values differ: one is set on participants while they are in the zone, the other (2) — right before
the creature is thrown out of the zone by teleporting it outside. The values nArg1 (zone attribute type,
@ZONEINFO_FREYA in calls) and nArg2 are passed to the client as a "zone effect", which the client
renders — so the exact interpretation of nArg2 (1/2 in calls) is left to the client side.
Returns nothing.
Signature
ChangeZoneInfo( CSharedCreatureData cCreature, int nArg1, int nArg2 )Parameters
cCreature (CSharedCreatureData) — the creature whose zone attribute is changed (in calls — a player in the Freya zone).
nArg1 (int) — which zone attribute to change; in calls the constant @ZONEINFO_FREYA.
nArg2 (int) — the attribute value (1 or 2 in calls); by context 2 is used when removing the creature from the zone, 1 — while it is inside it.Example
ChangeZoneInfo(creature, @ZONEINFO_FREYA, 2);IsStaticObjectIDNPC🟢 high
Checks whether nId is the identifier of a static object on the map; returns 1 if static. Creature method (CNPC).
Signature
IsStaticObjectID( int nId )Parameters
nId (int) — the identifier checked for belonging to a static object.Example
if (IsStaticObjectID(i0)) {Usage example
if ( IsStaticObjectID( i0 ) ) {
Say( MakeFString( 1110073, "", "", "", "", "" ) );
return;
}GetStaticObjectFromIDNPC🟢 high
Returns the static object structure (CSharedStaticObjectData) for identifier nId; used for interacting with static meshes and decorations. Creature method (CNPC).
Signature
GetStaticObjectFromID( int nId )Parameters
nId (int) — the identifier of the static object whose structure is needed.Example
so0 = GetStaticObjectFromID(i0);Usage example
so0 = GetStaticObjectFromID( i0 );
if ( StaticObjectDistFromMe( so0 ) >= 2500 ) { SayFStr( 1110074, _blank, _blank, _blank, _blank, _blank ); } else
{
if ( Skill_InReuseDelay( DDMagic ) ) { SayFStr( 1010551, _blank, _blank, _blank, _blank, _blank ); }
if ( Skill_GetConsumeMP( DDMagic ) < myself.sm.mp && Skill_GetConsumeHP( DDMagic ) < myself.sm.hp && Skill_InReuseDelay( DDMagic ) == 0 ) {
AddUseSkillDesireExByAction(i0, DDMagic, 0, reply, ask, 1000000, 0, action_id);
}
}SetStaticMeshStatusNPC🟢 high
Sets the parameters of the static mesh sMeshName on the object (CSharedCreatureData): bTargetable 0/1 — whether it can be targeted, nMeshIndex — mesh index in the list. No return value.
Signature
SetStaticMeshStatus( CSharedCreatureData object, string sMeshName, int bTargetable, int nMeshIndex )Parameters
object (CSharedCreatureData) — the object on which the static mesh is configured.
sMeshName (string) — static mesh name.
bTargetable (int) — targeting flag: 0 — cannot be targeted, 1 — can be.
nMeshIndex (int) — mesh index in the list.Example
SetStaticMeshStatus( c0, MeshName, targetable, mesh_index );
SetStaticMeshStatus( myself.c_ai0, MeshName, targetable, 0 );Usage example
if ( mesh_index > -1 ) {
SetStaticMeshStatus( myself.c_ai0, MeshName, targetable, 0 );
}SetWorldTrapVisibleByClassIdNPC🟢 high
Controls the visibility of a world trap by class nClassId: nVisibleFlag 0/1 — hidden/visible; also used to switch trap states. No return value.
Signature
SetWorldTrapVisibleByClassId( int nClassId, int nVisibleFlag )Parameters
nClassId (int) — the class of the world trap whose visibility is changed (usually myself.sm.class_id).
nVisibleFlag (int) — visibility flag: 0 — hidden, 1 — visible.Example
SetWorldTrapVisibleByClassId(myself.sm.class_id, show_detected);Usage example
if (IsDetected == 1) {
SetWorldTrapVisibleByClassId(myself.sm.class_id, show_detected);
}DefuseWorldTrapByClassIdNPC🟢 high
Defuses a world trap by nTrapId and nClassId; the trap loses its ability to trigger. No return value.
Signature
DefuseWorldTrapByClassId( int nTrapId, int nClassId )Parameters
nTrapId (int) — the identifier of the trap to defuse (usually myself.sm.id).
nClassId (int) — the class of the world trap (usually myself.sm.class_id).Example
DefuseWorldTrapByClassId(myself.sm.id, myself.sm.class_id);Usage example
if ( skill_name_id == trap_skill ) {
DefuseWorldTrapByClassId( myself.sm.id, myself.sm.class_id );
}ActivateWorldTrapByClassIdNPC🟢 high
Activates a world trap by nTrapId and nClassId; the trap becomes ready to trigger when its trigger is entered. No return value.
Signature
ActivateWorldTrapByClassId( int nTrapId, int nClassId )Parameters
nTrapId (int) — the identifier of the trap to activate (usually myself.sm.id).
nClassId (int) — the class of the world trap (usually myself.sm.class_id).Example
ActivateWorldTrapByClassId(myself.sm.id, myself.sm.class_id);Usage example
if ( script_event_arg1 == 12550 ) {
ActivateWorldTrapByClassId( myself.sm.id, myself.sm.class_id );
}RegisterAsAirportManagerNPC🟢 high
Registers the NPC as an airport manager: nAirportId, nPlatformId, nAirportType (0 — regular, 1 — premium, etc.); returns a result code (int).
Signature
RegisterAsAirportManager( int nAirportId, int nPlatformId, int nAirportType )Parameters
nAirportId (int) — airport identifier.
nPlatformId (int) — platform identifier.
nAirportType (int) — airport type (0 — regular, 1 — premium, etc.; 1 in calls).Example
myself.i_ai1 = RegisterAsAirportManager(airport_ID, platform_ID, 1);GetOnAirShipNPC🟢 high
Places the player talker (CSharedCreatureData) onto the airship platform (checks for available space and a ticket). No return value.
Signature
GetOnAirShip( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player placed onto the airship platformExample
GetOnAirShip(talker);Usage example
if (talker.yongma_type == 0) {
GetOnAirShip(talker);
} else {
ShowSystemMessage(talker, 2258);
}BuyAirShipNPC🟢 high
Sells the player talker (CSharedCreatureData) a ticket for ship nShipId (deducts adena, puts the ticket in the inventory). No return value.
Signature
BuyAirShip( CSharedCreatureData c, int nShipId )Parameters
c (CSharedCreatureData) — the player buying the ship ticket.
nShipId (int) — the identifier of the ship the ticket is sold for (2 in calls).Example
BuyAirShip(talker, 2);Usage example
if (OwnItemCount( talker, AirshipConfirm ) > 0) {
BuyAirShip(talker, 2);
} else {
ShowSystemMessageStr(talker, MakeFString(1800277, "", "", "", "", ""));
}SummonAirShipNPC🟢 high
Summons an airship to the airport platform for the player talker (CSharedCreatureData).
Argument order follows the real calls (SummonAirShip(talker, airport_ID, platform_ID)):
first the airport id, then the platform id. No return value.
Signature
SummonAirShip( CSharedCreatureData c, int nAirportId, int nPlatformId )Parameters
c (CSharedCreatureData) — the player for whom the airship is summoned.
nAirportId (int) — airport identifier (airport_ID in calls).
nPlatformId (int) — identifier of the summoning platform (platform_ID in calls).Example
SummonAirShip(talker, airport_ID, platform_ID);
SummonAirShip( talker, AIRPORT_ID, PLATFORM_ID );Usage example
if (OwnItemCount( talker, EnergyStone ) >= 5) {
SummonAirShip(talker, airport_ID, platform_ID);
} else {
ShowSystemMessageStr(talker, MakeFString(1800250, "", "", "", "", ""));
}IsOccupiedPlatformNPC🟢 high
Checks whether platform nPlatformId is occupied by a player or a ship; returns 1 if occupied.
Signature
IsOccupiedPlatform( int nPlatformId )Parameters
nPlatformId (int) — the identifier of the platform whose occupancy is checked (myself.i_ai1 in calls).Example
if (IsOccupiedPlatform(myself.i_ai1) == @FALSE)RegisterTeleporterTypeNPC🟢 high
Registers teleporter type nType with cost nCost; used for different groups of destinations (RaidBoss, Dungeon, etc.). Creature method (CNPC), no return value.
Signature
RegisterTeleporterType( int nType, int nCost )Parameters
nType (int) — teleporter type / destination group (1, 3 in calls).
nCost (int) — teleport cost (0, 40 in calls).Example
RegisterTeleporterType(1, 0);Usage example
if ( UseFreeTeleportBfr40lv == 1 ) {
RegisterTeleporterType( 3, 40 );
}ShowTelPosListPageNPC🟢 high
Shows the player talker (CSharedCreatureData) the list of available destinations posList (TelPosList) — usually special lists such as RaidBossList20_29. Creature method (CNPC), no return value.
Signature
ShowTelPosListPage( CSharedCreatureData c, CTelPosList posList )Parameters
c (CSharedCreatureData) — the player the destination list is shown to.
posList (CTelPosList) — the destination list to display (e.g. RaidBossList20_29).Example
ShowTelPosListPage( talker, RaidBossList20_29 );SendPostNPC🟢 high
Sends a letter to player nUserId with subject sTitle and body sMsg (usually via MakeFString), an adena amount nTradeMoney and up to 9 items (ID and quantity pairs); the letter arrives in the mailbox. Creature method (CNPC), no return value.
Signature
SendPost( int nUserDbId, string sTitle, string sMsg, int nTradeMoney, int nItemId1, int nItemAmount1, int nItemId2, int nItemAmount2, int nItemId3, int nItemAmount3, int nItemId4, int nItemAmount4, int nItemId5, int nItemAmount5, int nItemId6, int nItemAmount6, int nItemId7, int nItemAmount7, int nItemId8, int nItemAmount8, int nItemId9, int nItemAmount9 )Parameters
nUserDbId (int) — database identifier of the recipient player
sTitle (string) — letter subject
sMsg (string) — letter body (usually via `MakeFString`)
nTradeMoney (int) — amount of attached adena
nItemId1 (int) — identifier of attached item 1
nItemAmount1 (int) — quantity of attached item 1
nItemId2 (int) — identifier of attached item 2
nItemAmount2 (int) — quantity of attached item 2
nItemId3 (int) — identifier of attached item 3
nItemAmount3 (int) — quantity of attached item 3
nItemId4 (int) — identifier of attached item 4
nItemAmount4 (int) — quantity of attached item 4
nItemId5 (int) — identifier of attached item 5
nItemAmount5 (int) — quantity of attached item 5
nItemId6 (int) — identifier of attached item 6
nItemAmount6 (int) — quantity of attached item 6
nItemId7 (int) — identifier of attached item 7
nItemAmount7 (int) — quantity of attached item 7
nItemId8 (int) — identifier of attached item 8
nItemAmount8 (int) — quantity of attached item 8
nItemId9 (int) — identifier of attached item 9
nItemAmount9 (int) — quantity of attached item 9Example
case @kamaloka_29_d_boss: { SendPost(target.dbid, MakeFString(3681150, _blank, _blank, _blank, _blank, _blank), MakeFString(3681151, MakeFString(3681162, _blank, _blank, _blank, _blank, _blank), _blank, _blank, _blank, _blank), 0, inst_reward_bow_29, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0); break; }ShowSysMsgToParty2NPC🟢 high
Shows system message nSysMsgId to all members of the party (CSharedPartyData) with parameter substitution; nParamCount — number of parameters, then nParam1..4 and nValue. Creature method (CNPC), no return value.
Signature
ShowSysMsgToParty2( CSharedPartyData party, int nSysMsgId, int nParamCount, int nParam1, int nParam2, int nParam3, int nParam4 )Parameters
party (CSharedPartyData) — the party all of whose members are shown the message.
nSysMsgId (int) — system message identifier.
nParamCount (int) — number of substitution parameters passed.
nParam1 (int) — substitution parameter 1.
nParam2 (int) — substitution parameter 2.
nParam3 (int) — substitution parameter 3.
nParam4 (int) — substitution parameter 4 / value.Example
ShowSysMsgToParty2(party0, 2, 1381, 3, 5901, 1, i1);ShowVariationMakeWindowNPC🟢 high
Opens the item variation (augmentation) creation interface for the player talker (CSharedCreatureData). Creature method (CNPC), no return value.
Signature
ShowVariationMakeWindow( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player for whom the variation (augmentation) creation window is openedExample
ShowVariationMakeWindow(talker);Usage example
if (reply == 100) {
ShowVariationMakeWindow(talker);
} else
if (reply == 200) {
ShowVariationCancelWindow(talker);
}ShowVariationCancelWindowNPC🟢 high
Opens for the player talker (CSharedCreatureData) the interface for removing a variation from an item. Creature method (CNPC), no return value.
Signature
ShowVariationCancelWindow( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player for whom the variation removal window is openedExample
ShowVariationCancelWindow(talker);Usage example
if (reply == 200) {
ShowVariationCancelWindow(talker);
}ShowBaseAttributeCancelWindowNPC🟢 high
Opens for the player talker (CSharedCreatureData) the interface for removing an item's base attribute. No return value.
Signature
ShowBaseAttributeCancelWindow( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player for whom the base attribute removal window is openedExample
ShowBaseAttributeCancelWindow(talker);Usage example
if (reply == 611) {
ShowBaseAttributeCancelWindow(talker);
}NPC CREATION (NPC-create)
12 functionsCreatePrivatesNPC🟢 high
Spawns a whole group of subordinates by the set name sGroupName, predefined
in the NPC data. Takes one argument — a string with the set name (often the variablePrivates), no namespace. Returns nothing. The most frequent way to summon a
retinue or a wave of minions in a single call.
Signature
CreatePrivates( string sGroupName )Parameters
sGroupName (string) — the name of the subordinate set from the NPC data (often the variable Privates).Example
CreatePrivates(Privates);Usage example
if ( myself.sm.param1 == 4 ) {
CreatePrivates( Privates1 );
}CreateOnePrivateNPC🟢 high
Creates one subordinate NPC of the given class near the creator, without explicit
coordinates. Takes the NPC class nNpcClassId from [npc_pch], the AI name/type sName,
as well as nWeightPoint (spawn point/weight) and nRespawnTime (auto-respawn period) —
the latter two, unlike in the Ex version, are NOT user param slots, which is seen
from the named calls with the fields weight_point and respawn_time. Returns nothing.
Related event: on the created NPC, CREATED(reply) fires (see NASC_HANDLERS).
Signature
CreateOnePrivate( int nNpcClassId, string sName, int nWeightPoint, int nRespawnTime )Parameters
nNpcClassId (int) — the class of the created NPC.
the values are from the [npc_pch] dictionary
sName (string) — the AI name/type of the created NPC.
nWeightPoint (int) — the spawn point/weight (private.weight_point; often 0).
nRespawnTime (int) — the auto-respawn period, sec (private.respawn_time, 300, 280+Rand(40); 0=no respawn).Example
CreateOnePrivate( @grima, "grima", 0, 1 );Usage example
if ( private != myself.sm && private.respawn_time != 0 ) {
CreateOnePrivate( private.npc_class_id, private.ai, private.weight_point, private.respawn_time );
}CreateOneAnotherNPC🟢 high
Creates one independent NPC of the given class at the exact coordinates x, y, z
(not subordinate to the creator). Takes the NPC class nNpcClassId from [npc_pch], the AI name/type
sName, and three integer coordinates. Returns nothing. Used when
you need to place a mob or object at a specific spot in the world.
Signature
CreateOneAnother( int npc_class_id, string npc_name, int x, int y, int z )Parameters
npc_class_id (int) — the class of the created NPC.
the values are from the [npc_pch] dictionary
npc_name (string) — the AI name/type.
x (int) — the X coordinate.
y (int) — the Y coordinate.
z (int) — the Z coordinate.Example
CreateOneAnother(@ow_kegor, "ow_kegor", 114650, -114522, -11205);Usage example
if ( Rand( 1200 ) < 1 ) {
CreateOneAnother( @sia_champion_group, "sia_champion_group", pos0.x, pos0.y, pos0.z );
}CreateOnePrivateNearUserNPC🟢 high
Creates a subordinate NPC (private) near the specified player, rather than near the creator itself.
The NPC's spawn point is chosen not rigidly: it takes the player's location as the center and moves away from it by a
random distance within the given radius, in a random direction. The resulting point it
checks for passability (an NPC cannot be placed in a wall or underground) and on failure tries
another; the ready NPC it turns to face the player. Therefore two identical calls will give
subordinates in different spots around the player — this is convenient for "near the player" event spawns
(gifts, helpers, traps), when exact coordinates do not matter, what matters is proximity to the person.
The first argument is the player-center. The second — which NPC to create (a code from [npc_pch]). The third —
the behavior name/type (AI) of the newborn. The fourth — the subordinate's "weight": the higher it is, the more
actively the private draws enemies onto itself and the more it weighs in the target-priority calculations (usually the
creator's own weight is passed, myself.sm.weight_point). The last three numbers control placement
around the player; in a live call it is 1, 90, 60, and one of them sets the radius of the random scatter
from the player in world units. Returns nothing.
Related event: on the created NPC, CREATED fires (see NASC_HANDLERS).
Signature
CreateOnePrivateNearUser( CSharedCreatureData cUser, int nNpcClassId, string sName, int nWeightPoint, int nParam4, int nParam5, int nParam6 )Parameters
cUser (CSharedCreatureData) — the player around whom the subordinate appears (its location is the scatter center).
nNpcClassId (int) — which NPC to create; a code from the [npc_pch] dictionary.
sName (string) — the behavior name/type (AI) of the created NPC.
nWeightPoint (int) — the subordinate's "weight" in the aggro/target-priority calculations; usually `myself.sm.weight_point`.
nParam4 (int) — a placement parameter (1 in the call).
nParam5 (int) — a placement parameter (90 in the call); sets the radius of the random scatter around the player in world units.
nParam6 (int) — a placement parameter (60 in the call).Example
CreateOnePrivateNearUser( talker, @br_santa_white_gift, "br_santa_white_gift", myself.sm.weight_point, 1, 90, 60 );Usage example
if ( IsNullCreature( talker ) == 0 ) {
CreateOnePrivateNearUser( talker, @br_santa_white_gift, "br_santa_white_gift", myself.sm.weight_point, 1, 90, 60 );
}CreateOnePrivateExNPC🟢 high
A full spawn of one subordinate: the NPC class nNpcClassId from [npc_pch], the AI type
sAiType, the spawn point nWeightPoint, the delay nDelaySec, the exact coordinates x, y, z,
the rotation nHeading (client units, often as the product of an angle by 182), and three
user parameters nUser1..nUser3. Returns the result (the index/identifier of the
created creature). The decoding of the two middle numbers — per the L2NPC decompile
(CNPC::CreateOnePrivateEx_4B7D90): the engine sets AddTimer(obj, 1000*nDelaySec, 0),
i.e. the 4th argument is the spawn delay in seconds; the 3rd argument is placed into the spawn-point
field (in calls literally private.weight_point is found, as with CreateOnePrivate).
The last three numbers are arbitrary user slots: the engine places them into the created
creature, and it reads them as myself.sm.param1/param2/param3, while other scripts — as
param1/param2/param3 of this creature; there the owner or target index, dbid,
a tag, coordinates are stored — the meaning is set by the script itself.
Related event: on the created NPC, CREATED(reply) fires (see NASC_HANDLERS).
Signature
CreateOnePrivateEx( int nNpcClassId, string sAiType, int nWeightPoint, int nDelaySec, int x, int y, int z, int nHeading, int nUser1, int nUser2, int nUser3 )Parameters
nNpcClassId (int) — the NPC class.
the values are from the [npc_pch] dictionary
sAiType (string) — the AI-type name (e.g. myself.sm.ai, "HelpHeroAI").
nWeightPoint (int) — the spawn point/weight (in calls 0, 10, private.weight_point).
nDelaySec (int) — the spawn delay in seconds (engine: AddTimer(1000*nDelaySec);
0 = immediately; 5, Rand(5), 20, 30+Rand(60) are found).
x (int) — the X coordinate (FloatToInt(...)).
y (int) — the Y coordinate.
z (int) — the Z coordinate.
nHeading (int) — the rotation (client units; i0*182, 32768=180°, full circle 65536).
nUser1 (int) — user data → created.param1.
nUser2 (int) — user data → created.param2.
nUser3 (int) — user data → created.param3.Example
CreateOnePrivateEx( @mikhail, "mikhail", 10, 5, 178304, -17712, -2194, 32768, 0, 0, 0 );Usage example
if ( HavePet == 1 ) {
CreateOnePrivateEx( silhouette, ai_type, 0, 0, FloatToInt( ( myself.sm.x + 10 ) ), FloatToInt( ( myself.sm.y + 10 ) ), FloatToInt( myself.sm.z ), 0, 0, 0, 0 );
}CreateOnePrivateInzoneExNPC🟢 high
Does the same as CreateOnePrivateEx, but the spawn happens inside an instant zone:
the last, twelfth argument nZoneId — the zone/instance id — is added. Per the L2NPC decompile
(CNPC::CreateOnePrivateInzoneEx_4B7BE4) the argument layout matches Ex:
the same AddTimer(obj, 1000*nDelaySec, 0) (the 4th argument is the delay in seconds), the 3rd —
the spawn point; the three numbers before the zone are the user slots nUser1..nUser3 (placed
into the created creature as param1/param2/param3). Returns the index of the created creature.
Related event: on the created NPC, CREATED(reply) fires (see NASC_HANDLERS).
Signature
CreateOnePrivateInzoneEx( int nNpcClassId, string sAiType, int nWeightPoint, int nDelaySec, int x, int y, int z, int nHeading, int nUser1, int nUser2, int nUser3, int nZoneId )Parameters
nNpcClassId (int) — the class of the created NPC.
the values are from the [npc_pch] dictionary
sAiType (string) — the AI-type name of the created NPC.
nWeightPoint (int) — the spawn point/weight (in calls usually 0).
nDelaySec (int) — the spawn delay in seconds (engine: AddTimer(1000*nDelaySec); 0 = immediately).
x (int) — the X coordinate of the spawn point.
y (int) — the Y coordinate of the spawn point.
z (int) — the Z coordinate of the spawn point.
nHeading (int) — the rotation (client units; 32768=180°, full circle 65536).
nUser1 (int) — user data → created.param1.
nUser2 (int) — user data → created.param2.
nUser3 (int) — user data → created.param3.
nZoneId (int) — the zone/instance id of the spawn (usually InstantZone_GetId()).Example
CreateOnePrivateInzoneEx(i1, "warriors_of_rest", 0, 0, 55672, -252728, -6760, 0, 0, 2, 0, InstantZone_GetId());Usage example
if ( timer_id == 1001 ) {
CreateOnePrivateInzoneEx( @portrait_spirit_winged, "ai_boss08_portrait_spirit_winged", 0, 0, SpawnPosX, SpawnPosY, SpawnPosZ, SpawnAngle, 0, 0, 0, InstantZone_GetId( ) );
}CreatePetNPC🟢 high
Creates a pet for the owner cOwner from the summon item nItemClassId (a whistle or
ocarina) with the appearance/class of the NPC nNpcClassId and the given level. The fourth argument —
the pet's level: in real calls this is talker.level or the numbers 1, 15, 24, 25, 26,
55, matching the hatchling's level. Returns nothing. Used by NPC pet-breeders
when "activating" a hatchling from a purchased ticket.
Signature
CreatePet( CSharedCreatureData cOwner, int nItemClassId, int nNpcClassId, int nLevel )Parameters
cOwner (CSharedCreatureData) — the future owner of the pet.
nItemClassId (int) — the pet summon item.
the values are from the [item_pch] dictionary
nNpcClassId (int) — the class/appearance of the pet.
the values are from the [npc_pch] dictionary
nLevel (int) — the level of the created pet (in calls talker.level or 1/15/24/25/26/55).Example
CreatePet( talker, @wolf_collar, @pet_wolf_a, 15 );Usage example
if ( i0 < 75 ) {
CreatePet( talker, @dragonflute_of_star, @hatchling_of_star, 35 );
} else {
CreatePet( talker, @dragonflute_of_twilight, @hatchling_of_twilight, 35 );
}CreateSubPledgeNPC🟢 high
Creates a sub-unit (royal guard / knight) for the player's clan. The clan is taken from the passed
creature. The operation is asynchronous: L2NPC assembles an atomic-job, the server (AtomicCreateSubPledge::Do →
CDB::RequestCreateSubPledgeByNpc) invokes the creation of the sub-unit in the DB. By the signature of the server
function, its third parameter has the type enum PledgeType — this is nType. It immediately returns zero;
the actual result arrives as a separate event. If the creature has no clan, the task is not created.
Signature
CreateSubPledge( CSharedCreatureData c, int nType, int nParam, string sName )Parameters
c (CSharedCreatureData) — the creature for whose clan the sub-unit is created.
nType (int) — the sub-unit type (enum PledgeType, confirmed by the server function's signature):
100 royal guard 1, 200 royal guard 2, 1001/1002 knight 1/2, 2001/2002 knight 3/4.
nParam (int) — an additional creation parameter, passed to the DB request for creating the sub-unit (DB packet opcode 247).
sName (string) — the name of the sub-unit (up to 24 characters).Example
CreateSubPledge(talker, i0, i1, s0);CreateSubJobNPC🟢 high
Sets up a subclass for the player — a second profession he can switch to. The first
argument is the player himself, the second — which profession to open (its class_id). The result arrives not
immediately: in response to the addition of a subclass, the player receives the SUBJOB_CREATED event, in which it is
checked whether it succeeded (for example, whether the subclass limit is not exceeded, whether the class fits). In
the conditions before the call they usually look at the player's current profession and already-existing subclasses,
so as not to open a forbidden or duplicating combination.
Signature
CreateSubJob( CSharedCreatureData c, int nClassId )Parameters
c (CSharedCreatureData) — the creature for whom the subclass (second profession) is created.
nClassId (int) — the class id of the created profession (occupation from [class_pch];
in calls @berserker and the numbers 2, 12, 13, 14, 16, 17, 20, 21, 23, 24 — these are the profession's class_id).Example
CreateSubJob( talker, @berserker );Usage example
if ( i0 != 12 && i0 != 94 && i2 != 12 && i2 != 94 && i4 != 12 && i4 != 94 && i6 == -1 && ( IsInCategory( @third_class_group, i0 ) || IsInCategory( @fourth_class_group, i0 ) ) ) {
CreateSubJob( talker, 12 );
}
Related event: the server's response arrives as the SUBJOB_CREATED event (see NASC_HANDLERS).CreateAcademyNPC🟢 high
Creates a clan academy for the player's clan with the specified name (up to 24 characters).
Asynchronous (an internal task): returns one if the task was placed, and zero
if a creature was not passed. The clan is taken from the creature.
Signature
CreateAcademy( CSharedCreatureData c, string sName )Parameters
c (CSharedCreatureData) — the creature for whose clan the academy is created.
sName (string) — the academy name (up to 24 characters).Example
CreateAcademy(talker, s0);CreatePVPMatchNPC🟢 high
Creates/starts a PvP match in the slot with the given number. The number must be from 0 to 8
(otherwise the engine logs an error and does nothing). Sends the server the command
to create the match of this slot. Returns nothing.
Signature
CreatePVPMatch( int nMatchSlot )Parameters
nMatchSlot (int) — the match slot index, 0..8 (otherwise the engine logs an error and does nothing).Example
CreatePVPMatch( i0 );
CreatePVPMatch(nType);CreateBingoBoardNPC🟢 high
Creates a square bingo board (minigame) with side nBoardSize for a player. Per the L2NPC decompile
(User::CreateBingoBoard_5B4CEC) the second argument is the board's side length: the engine builds
nBoardSize×nBoardSize cells and rejects EVEN values (the side must be odd);
in calls 3 is passed → a 3×3 board (9 cells). If the player is not found or the side is even —
returns zero.
Signature
CreateBingoBoard( CSharedCreatureData c, int nBoardSize )Parameters
c (CSharedCreatureData) — the player for whom the bingo board is created.
nBoardSize (int) — the side length of the square board (odd; the board is nBoardSize²);
in calls 3 (a 3×3 board). The engine rejects even values.Example
CreateBingoBoard(talker, 3);FINDING AND GETTING CREATURES (Target-finding)
75 functionsGetCreatureFromIndexGLOBAL🟢 high
Returns a creature by its session index nIndex — the creature's temporary slot in server memory, valid while the creature is "alive" in the world. Single argument: nIndex (int, no namespace; −1 = none). Belongs to gg; if the index is invalid, an "empty" creature is returned, so the result is checked via IsNullCreature, or the index itself is compared against −1 beforehand.
Signature
GetCreatureFromIndex( int nIndex )Parameters
nIndex (int) — session index of the creature (−1 = none).Example
c0 = GetCreatureFromIndex( i0 );Usage example
c1 = GetCreatureFromIndex( i1 );
if ( IsNullCreature( c1 ) == 0 ) { SendScriptEvent( c1, GetIndexFromCreature( myself.sm ), 0 ); }GetCreatureFromIDGLOBAL🟢 high
Returns a creature by its permanent object ID nID — the same one stored in the creature's id field. Single argument: nID (int, no namespace). Belongs to gg; the ID is more reliable than the index and convenient for storing in lists and instance "rooms", and on a miss the function returns an "empty" creature (check with IsNullCreature).
Signature
GetCreatureFromID( int nID )Parameters
nID (int) — permanent ID of the creature (creature.id).Example
c0 = GetCreatureFromID(GetGlobalMap(@gm_cartia_adolf));Usage example
c0 = GetCreatureFromID( room0.GetMemberID( i0 ) );
if ( HaveMemo( c0, @in_the_dimension_rift ) ) {
SetMemoStateEx( c0, @in_the_dimension_rift, 1, -1 );
}GetCreatureExFromIndexGLOBAL🟢 high
Given a creature's numeric index, returns its "extended" object (CSharedCreatureDataEx) —
a superstructure over the regular creature object with additional fields absent from the base one.
Useful when only an index is at hand but access to the extended properties is needed. Paired
with GetCreatureEx, which does the same but starts from an already available base object rather
than an index. Returns an empty result for an invalid index.
Signature
GetCreatureExFromIndex( int nSMIndex )Parameters
nSMIndex (int) — numeric index of the creature whose extended object is taken.
Example (illustrative):
GetCreatureExFromIndex( nSMIndex );GetCreatureExGLOBAL🟢 high
Given an already available regular creature object, returns its "extended" object
(CSharedCreatureDataEx) — a superstructure with additional fields on top of the base one. Same as
GetCreatureExFromIndex, except the starting point is not a numeric index but the creature object itself
(e.g. talker). Returns an empty result for an empty object.
Signature
GetCreatureEx( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — regular creature object whose extended object is taken.
Example (illustrative):
GetCreatureEx( talker );Spawn2MAKER🟢 high
Creates the given number of creatures of this define. Arguments: nCount (int) — how many to spawn; nRespawnTime (int) — auto-respawn period (zero disables it); nRespawnRand (int) — random spread added to the period. If the respawn time is zero, there is no auto-revival; otherwise, after death the creature respawns after the specified time with the spread. Called on a define ([CNpcSpawnDefineEx]).
Related event: on the maker — ON_NPC_CREATED/ON_NPC_DELETED; on the new NPC — CREATED (see NASC_HANDLERS).
Signature
Spawn2( int nCount, int nRespawnTime, int nRespawnRand )Parameters
nCount (int) — how many creatures to spawn.
nRespawnTime (int) — auto-respawn period (zero disables auto-revival).
nRespawnRand (int) — random spread added to the respawn period.Example
def0.Spawn2(i2, 0, 0);SpawnExMAKER🟢 high
Spawns creatures at an explicit position and restores their state from a database record; used at world load. Arguments: nCount (int) — how many to spawn; nMode (int) — mode; x, y, z (int) — coordinates; nHeading (int) — heading (65536 = 360°); nHp, nMp (int) — HP and MP; nDbValue (int) — stored value. Called on a define ([CNpcSpawnDefineEx]).
Signature
SpawnEx( int nCount, int nMode, int nX, int nY, int nZ, int nHeading, int nHp, int nMp, int nDbValue )Parameters
nCount (int) — how many creatures to spawn
nMode (int) — spawn mode
nX (int) — X coordinate of the spawn point
nY (int) — Y coordinate of the spawn point
nZ (int) — Z coordinate of the spawn point
nHeading (int) — heading (65536 = 360°)
nHp (int) — current health (HP) value of the creature
nMp (int) — current mana (MP) value of the creature
nDbValue (int) — value stored in the database, restored for the creatureExample
loaded_def.SpawnEx(1, 0, record0.x, record0.y, record0.z, 0, record0.hp, record0.mp, record0.db_value);SpawnMAKER🟢 high
Creates the given number of creatures of this define. Arguments: nCount (int) — how many to spawn; nRespawnTime (int) — respawn period. Called on a define ([CNpcSpawnDefineEx]). No explicit calls were found in the collected scripts.
Signature
Spawn( int nCount, int nRespawnTime )Parameters
nCount (int) — how many creatures to spawn
nRespawnTime (int) — respawn periodExample
def0.Spawn(1, 0);GetNpcMakerGLOBAL🟢 high
This is how a regular NPC reaches a maker, finding it by name. Argument sName (string) — the maker's name; called on the global object gg. The result is null-checked via IsNull. Returns a [CNpcMakerEx] object.
Signature
GetNpcMaker( string pwsName )Parameters
pwsName (string) — name of the maker to search forExample
maker0 = GetNpcMaker( s0 );Usage example
maker0 = GetNpcMaker( evilate_maker1 );
if ( IsNull( maker0 ) == 0 ) { SendMakerScriptEvent( maker0, 1000, 0, 0 ); }GetMyMakerNPC🟢 high
Returns the maker that spawned this NPC — a direct reference to its creator.
No arguments; called on myself. Unlike GetNpcMaker (which finds a maker by name),
here the name need not be known: the NPC gets exactly its own spawner. Handy for reporting
back to the creator (wave counters, spawn relay). If the NPC has no bound maker, returns
empty — the result is checked via IsNull.
Signature
GetMyMaker( )Parameters
(none — the function is called without arguments)Example
maker0 = myself.GetMyMaker();
if ( IsNull( maker0 ) == 0 ) { SendMakerScriptEvent( maker0, 1001, 0, 0 ); }IsTournamentEnableGLOBAL🟢 high
Tells whether a tournament is currently running at all: returns @TRUE if the tournament is open
(registration is possible, the schedule can be shown, spectators admitted), and @FALSE if it is
closed. With this check the gate script decides whether to open the tournament menu
at all and offer registration: while the function returns @FALSE, all tournament actions must be suppressed.
No arguments, read-only.
Signature
IsTournamentEnable( )Parameters
(none — the function is called without arguments)Example
if (IsTournamentEnable() == @TRUE)IsTournamentGroupStageGLOBAL🟢 high
Distinguishes the two tournament phases: returns @TRUE during the group stage and @FALSE when
the finals (playoffs) are running. The answer determines how to register a player: during the group stage
registration is automatic for the current group match, while in the finals the player must enter
the code of their match (see AddTournament — its second argument is chosen exactly by this check).
No arguments, read-only.
Signature
IsTournamentGroupStage( )Parameters
(none — the function is called without arguments)Example
if (IsTournamentGroupStage() == @TRUE)IsInCategoryNPC🟢 high
Checks whether the value nValue (usually a creature's class or occupation) belongs to category nCategory from the [category_pch] dictionary. Arguments: nCategory (int, namespace [category_pch]) and nValue (int, no namespace); belongs to myself, returns 1 (belongs) or 0. Main uses are telling "own" summons, pets and servitors apart from live players and sorting targets by role (fighter, healer).
Signature
IsInCategory( int nCategory, int nValue )Parameters
nCategory (int) — which category is checked.
values — from the [category_pch] dictionary
nValue (int) — the value being checked (usually the creature's .class_id / .occupation).Example
if ( IsInCategory( @second_class_group, talker.occupation ) ) {Usage example
if ( IsInCategory( @summon_npc_group, target.class_id ) != 0 ) {
AddAttackDesire( target.master, @AMT_MOVE_TO_TARGET, 500 );
}FindRandomUserNPC🟢 high
Asynchronously asks the engine to pick a random player in the zone by filters and returns nothing itself (void type). The four arguments (no namespace) are selection filters: nInCombat (in combat only), nNotInPeaceZone (not in a peace zone), nNotInOlympiad (not at the Olympiad), nInParty (in a party only); belongs to myself. The chosen player arrives later in the FIND_RANDOM_USER event handler, where it sits in the talker parameter — the typical "request now, answer in the handler" pattern.
Related event: the found player arrives via the FIND_RANDOM_USER(talker) event (see NASC_HANDLERS).
Signature
FindRandomUser( int nInCombat, int nNotInPeaceZone, int nNotInOlympiad, int nInParty )Parameters
nInCombat (int) — 1 = only players in combat, 0 = no such filter.
nNotInPeaceZone (int) — 1 = exclude players in a peace zone, 0 = no filter.
nNotInOlympiad (int) — 1 = exclude players at the Olympiad, 0 = no filter.
nInParty (int) — 1 = only players in a party, 0 = no filter.Example
FindRandomUser(0, 0, 0, 0);
FindRandomUser( 1, 1, 1, 1 );Usage example
if (GetGlobalMap(99) == 1) {
FindRandomUser(1, 1, 1, 1);
AddTimerEx(1227, 300000);
}DespawnNPC🟢 high
Removes (despawns) all NPCs of this define. Takes no arguments; called on a define ([CNpcSpawnDefineEx]).
Signature
Despawn( )Parameters
(none — the function is called without arguments)Example
Despawn();Usage example
if ( private == myself.boss ) {
Despawn( );
}Maker_GetNpcCountNPC🟢 high
Tells how many NPCs are currently spawned by this maker — handy for "am I the last of the wave?" logic. Takes no arguments; called on myself ([CNPC]). Returns int.
Signature
Maker_GetNpcCount( )Parameters
(none — the function is called without arguments)Example
if ( script_event_arg1 == @SCE_ANTARAS_USE_FEAR && Maker_GetNpcCount( ) < 150 ) {Usage example
if ( Maker_GetNpcCount( ) == 1 ) {
CreateOnePrivateEx( @first_orc, "first_orc", 0, 0, 21036, -107690, -3038, 0, 0, 0, 0 );
}Maker_FindNpcByKeyNPC🟢 high
Looks up a sibling spawned by the same maker by its key — usually the third spawn parameter, sm.param3. The argument nKey (int) is the key of the NPC being searched for; called on myself ([CNPC]). The result is checked like a creature. Returns a [CSharedCreatureData] object.
Signature
Maker_FindNpcByKey( int nKey )Parameters
nKey (int) — key of the NPC being searched for (usually the third spawn parameter, `sm`.param3).Example
c0 = Maker_FindNpcByKey( i0 );
c0 = Maker_FindNpcByKey( myself.sm.param3 );Usage example
c0 = Maker_FindNpcByKey( i0 );
if ( c0 ) {
AddAttackDesire( c0, @AMT_MOVE_TO_TARGET, 100000 );
}SoundEffectNPC🟢 high
Plays a short sound to a player by client resource name. Takes the listener
and the sound name string; called on an NPC (myself), returns nothing. The main
use is quest stage sounds: taking a quest, an intermediate step, obtaining an
item and completion.
Signature
SoundEffect( CSharedCreatureData c, string sSoundName )Parameters
c (CSharedCreatureData) — the listener (player) the sound is played to.
sSoundName (string) — client sound resource name (e.g. "Itemsound.quest_middle").Example
SoundEffect( c1, "Itemsound.quest_middle" );EffectMusicNPC🟢 high
Turns on background music in a radius around the source — in the examples these are boss battle themes.
Per the L2NPC decompile (CNPC::EffectMusic_48943C) the second argument is the broadcast distance:
the engine's error string reads "nDist<=0 or nDist>16384", i.e. the audibility radius, which
must lie in the range 1..16384 (the music goes out to clients within this radius, packet opcode 70).
Called on an NPC, returns nothing.
Signature
EffectMusic( CSharedCreatureData c, int nDist, string sTrack )Parameters
c (CSharedCreatureData) — the music source (usually the NPC itself via `sm`).
nDist (int) — music audibility radius, 1..16384 (the engine rejects 0 and >16384; 7000 in the calls).
sTrack (string) — music track name (e.g. "BS01_A", "SSQ_Dawn_01").Example
EffectMusic(myself.sm, 7000, "BS01_A");Usage example
if ( GetSSQWinner( ) == 2 ) {
EffectMusic( myself.sm, 0, "SSQ_Dawn_01" );
}VoiceEffectNPC🟢 high
Plays a voice-over — a regular voice at the given volume, for example
tutorial hints. Takes the listener, the voice file and the volume; called on an NPC,
returns nothing.
Signature
VoiceEffect( CSharedCreatureData c, string sFileName, int nVolume )Parameters
c (CSharedCreatureData) — the listener (player) the voice-over is played to.
sFileName (string) — voice-over file (e.g. "tutorial_voice_026").
nVolume (int) — playback volume (0 or 1000 in the calls).Example
VoiceEffect(talker, "tutorial_voice_026", 1000);Usage example
if ( GetMemoStateEx( talker, @tutorial_quest, 1 ) == 3 && timer_id >= 1000000 ) {
VoiceEffect( talker, "tutorial_voice_010d", 0 );
}VoiceNPCEffectNPC🟢 high
Plays an NPC voice line. Takes the listener, the voice file and a numeric mode
id (always zero in the calls); called on an NPC, returns nothing. The third
argument has not been reliably identified.
Signature
VoiceNPCEffect( CSharedCreatureData cCreature, string pwsFileName, int nVoiceNPCEffectId )Parameters
cCreature (CSharedCreatureData) — the listener (player) the NPC voice line is played to
pwsFileName (string) — NPC voice-over file
nVoiceNPCEffectId (int) — voice mode id (always zero in the calls, meaning not disclosed)Example
VoiceNPCEffect(h0.creature, s0, 0);StartScenePlayerNPC🟢 high
Starts a scripted movie (cutscene) for a player by its identifier. Takes
the viewer and the numeric scene id; called on an NPC, returns nothing. The identifier
appears both as a raw number and as named constants (boss scene name, scene
number, etc.) declared in the script class itself.
Related event: when the scene finishes — SCENE_STOPPED (see NASC_HANDLERS).
Signature
StartScenePlayer( CSharedCreatureData c, int nSceneId )Parameters
c (CSharedCreatureData) — the viewer (player) the cutscene is started for.
nSceneId (int) — identifier of the cutscene to start (a raw number or a named scene constant).Example
StartScenePlayer(talker, 9);StartScenePlayerAroundNPC🟢 high
Starts a cutscene for all players near a point — within a radius and a height
range. Takes the viewer, the scene id, the radius and the lower/upper height
bounds; called on an NPC, returns nothing.
Related event: when the scene finishes — SCENE_STOPPED (see NASC_HANDLERS).
Signature
StartScenePlayerAround( CSharedCreatureData c, int nSceneId, int nRadius, int nLowZ, int nHighZ )Parameters
c (CSharedCreatureData) — the reference point (usually myself.sm) for showing the scene to those around.
nSceneId (int) — identifier of the cutscene to start.
nRadius (int) — horizontal coverage radius within which players are shown the scene.
nLowZ (int) — lower height bound of the coverage (Z coordinate).
nHighZ (int) — upper height bound of the coverage (Z coordinate).Example
StartScenePlayerAround(myself.sm, 1, 4000, 1100, 3100);
StartScenePlayerAround(myself.sm, 7, 8000, -11972, -11772);
StartScenePlayerAround(myself.sm, 6, 8000, -11972, -11772);
StartScenePlayerAround(myself.sm, 5, 8000, -11972, -11772);Usage example
if (myself.i_ai1 == 4) {
StartScenePlayerAround(myself.sm, 27, 8000, FloatToInt(myself.sm.z - 1000), FloatToInt(myself.sm.z + 1000));
}StartScenePlayerToPartyNPC🟢 high
Starts a cutscene for the player's entire party. Takes the viewer and the scene id;
called on an NPC, returns nothing.
Related event: when the scene finishes — SCENE_STOPPED (see NASC_HANDLERS).
Signature
StartScenePlayerToParty( CSharedCreatureData c, int nSceneId )Parameters
c (CSharedCreatureData) — the initiator whose party the cutscene is started for.
nSceneId (int) — identifier of the cutscene to start.
Example (illustrative):
StartScenePlayerToParty( talker, nSceneId );PlaySceneNPC🟢 high
Plays a cutscene with the given index (client scene id) to a player. Called
on an NPC, returns nothing. Requires a non-null player and a non-negative scene
index (otherwise the engine writes an error to the log). It is a working presentation command, not
a "deprecated" one: it simply sends the scene start command to the client.
Signature
PlayScene( CSharedCreatureData c, int nSceneIndex )Parameters
c (CSharedCreatureData) — the player the cutscene is played to.
nSceneIndex (int) — cutscene index (client id, >= 0).
Example (illustrative):
PlayScene( talker, nSceneIndex );SpecialCameraNPC🟢 high
Turns on a cinematic (staged) camera for all players around the target, aimed
at that target — the picture temporarily detaches from the character and shows the scene from the side.
A single call shows just one angle; a whole movie (boss flyby, dramatic entrance)
is assembled from a chain of such calls in a row on a timer. The camera itself is drawn by the client: the server merely
passes the flyby numbers to it as-is. The leading fields are clear (distance, angles, timings), while
the rest are fine flyby tuning interpreted by the client. Called on an NPC, returns
nothing.
Signature
SpecialCamera( CSharedCreatureData c, int nDist, int nYaw, int nPitch, int nTime, int nDuration, int nTurn, int nRise, int nParam8, int nParam9, int nParam10, int nParam11 )Parameters
c (CSharedCreatureData) — the target the camera looks at (usually the boss itself, myself.sm).
nDist (int) — how far the camera stands off from the target (500, 700, 1700 in the calls).
nYaw (int) — horizontal camera rotation around the target (small degree numbers: 10, 13, 88).
nPitch (int) — vertical camera tilt (above/below the target line: 0, 4, -19).
nTime (int) — how many milliseconds the camera takes to glide to the given position (0, 300, 5000, 6000 in the calls).
nDuration (int) — how many milliseconds this angle is held (5000, 10000, 15000 in the calls).
nTurn (int) — numeric camera-motion field for the segment (turn/movement; 250, 10000, 20000 in the calls). Exact meaning unconfirmed.
nRise (int) — numeric camera-motion field for the segment (0, 20 in the calls). Exact meaning unconfirmed.
nParam8 (int) — client-side camera tuning field (0, -20 in the calls).
nParam9 (int) — client-side camera tuning field (0, 1 in the calls).
nParam10 (int) — client-side camera tuning field (0, 1 in the calls).
nParam11 (int) — client-side camera tuning field (0, 1 in the calls).Example
SpecialCamera(myself.sm, 500, 88, 4, 5000, 5000, 10000, 0, 0, 1, 0, 1);Usage example
if ( timer_id == 1117 ) {
SpecialCamera( myself.sm, 1700, 10, 0, 300, 15000, 250, 20, -20, 1, 1, 0 );
}SpecialCamera3NPC🟢 high
Another variant of the staged camera from the same family as SpecialCamera — with the same
set of eleven numeric angle and timing settings. It differs in the camera's behavior
on the segment (the calls show a different combination of numbers), but the purpose and the way
it is used are the same: show everyone around the target the scene from the side, and assemble
a movie from a chain of calls. The picture is drawn by the client: the server passes the flyby numbers as-is. Called
on an NPC, returns nothing.
Signature
SpecialCamera3( CSharedCreatureData c, int nDist, int nYaw, int nPitch, int nTime, int nDuration, int nTurn, int nRise, int nParam8, int nParam9, int nParam10, int nParam11 )Parameters
c (CSharedCreatureData) — the target the camera looks at (usually the boss itself).
nDist (int) — how far the camera stands off from the target (250, 300 in the calls).
nYaw (int) — horizontal camera rotation around the target (180, 220 in the calls).
nPitch (int) — vertical camera tilt (0, 20 in the calls).
nTime (int) — how many milliseconds the camera takes to reach the given position (0, 3000 in the calls).
nDuration (int) — how many milliseconds the angle is held (5000 in the calls).
nTurn (int) — numeric camera-motion field for the segment (10000 in the calls). Exact meaning unconfirmed.
nRise (int) — numeric camera-motion field for the segment (0 in the calls). Exact meaning unconfirmed.
nParam8 (int) — client-side camera tuning field (0, 6 in the calls).
nParam9 (int) — client-side camera tuning field (1 in the calls).
nParam10 (int) — client-side camera tuning field (1 in the calls).
nParam11 (int) — client-side camera tuning field (1 in the calls).Usage example
if ( timer_id == 2002 ) {
SpecialCamera3( myself.sm, 0, 180, 80, 4000, 5000, 6000, 0, 0, 1, 1, 1 );
AddTimerEx( 2003, 6000 );
}SpecialCameraExNPC🟢 high
A staged camera with two targets: one sets the point the camera looks from, the other —
what it is aimed at. Handy when a scene must be shown as a link between two creatures (for example,
a gaze from one character toward another). Then come nine numeric flyby fields — the same
angle and timing settings as in regular SpecialCamera; the picture is drawn by the client, the server
passes the numbers as-is. Called on an NPC, returns nothing.
Signature
SpecialCameraEx( CSharedCreatureData cFrom, CSharedCreatureData cTo, int nDist, int nYaw, int nPitch, int nTime, int nDuration, int nParam7, int nParam8, int nParam9, int nParam10 )Parameters
cFrom (CSharedCreatureData) — the creature the view is taken from (the shooting point).
cTo (CSharedCreatureData) — the creature the camera is aimed at.
nDist (int) — how far the camera stands off from the target.
nYaw (int) — horizontal camera rotation.
nPitch (int) — vertical camera tilt.
nTime (int) — how many milliseconds the camera takes to reach the given position.
nDuration (int) — how many milliseconds the angle is held.
nParam7 (int) — client-side camera tuning field.
nParam8 (int) — client-side camera tuning field.
nParam9 (int) — client-side camera tuning field.
nParam10 (int) — client-side camera tuning field.
Example (illustrative):
SpecialCameraEx( talker, talker, nDist, nYaw, nPitch, nTime, nDuration, nParam7, nParam8, nParam9, nParam10 );SpecialCameraZLimitNPC🟢 high
The same staged camera as SpecialCamera, but with two extra numbers —
the lower and upper height bounds (Z coordinate). They keep the camera within the given
height range so it does not dive underground or fly too high on uneven
terrain. The remaining fields are the usual angle and timing settings; the picture is drawn by the
client, the server passes the numbers as-is. Called on an NPC, returns nothing.
Signature
SpecialCameraZLimit( CSharedCreatureData c, int nDist, int nYaw, int nPitch, int nTime, int nDuration, int nTurn, int nRise, int nParam8, int nParam9, int nParam10, int nParam11, int nLowZ, int nHighZ )Parameters
c (CSharedCreatureData) — the target the camera looks at (usually the boss itself).
nDist (int) — how far the camera stands off from the target.
nYaw (int) — horizontal camera rotation.
nPitch (int) — vertical camera tilt.
nTime (int) — how many milliseconds the camera takes to reach the given position.
nDuration (int) — how many milliseconds the angle is held.
nTurn (int) — numeric camera-motion field for the segment. Exact meaning unconfirmed.
nRise (int) — numeric camera-motion field for the segment. Exact meaning unconfirmed.
nParam8 (int) — client-side camera tuning field.
nParam9 (int) — client-side camera tuning field.
nParam10 (int) — client-side camera tuning field.
nParam11 (int) — client-side camera tuning field.
nLowZ (int) — lower height bound: do not lower the camera below this level.
nHighZ (int) — upper height bound: do not raise the camera above this level.
Example (illustrative):
SpecialCameraZLimit( talker, nDist, nYaw, nPitch, nTime, nDuration, nTurn, nRise, nParam8, nParam9, nParam10, nParam11, nLowZ, nHighZ );EarthQuakeByNPCNPC🟢 high
Shakes the screen for viewers around the target — for dramatic moments in boss fights. The shake itself
is rendered by the client: the server passes it six numbers as-is. The first two are the intensity and
duration, the other four are client-side effect fields (1/1/1/0 in the calls). Called
on an NPC, returns nothing.
Signature
EarthQuakeByNPC( CSharedCreatureData c, int nIntensity, int nDuration, int nParam3, int nParam4, int nParam5, int nParam6 )Parameters
c (CSharedCreatureData) — the shake epicenter (often the NPC itself, myself.sm).
nIntensity (int) — screen shake intensity (40, 50 in the calls).
nDuration (int) — shake duration (4, 10 in the calls).
nParam3 (int) — client-side shake effect field (opcode 59). [need_client]
nParam4 (int) — client-side shake effect field (opcode 59). [need_client]
nParam5 (int) — client-side shake effect field (opcode 59). [need_client]
nParam6 (int) — client-side shake effect field (opcode 59). [need_client]Example
EarthQuakeByNPC(myself.sm, 50, 4, 1, 1, 1, 0);Usage example
if ( timer_id == 2006 ) {
EarthQuakeByNPC( myself.sm, 40, 10, 1, 0, 0, 0 );
EffectMusic( myself.sm, 6000, "BS02_A" );
}EarthQuakeToPartyNPC🟢 high
Shakes the screen for all members of one party — wherever they are, the shake
is received specifically by members of the given party, not everyone around some point. Used for
dramatic moments inside an instant zone/room where the action targets a party. The shake itself
is drawn by the client. Returns nothing.
Signature
EarthQuakeToParty( int nPartyId, int nIntensity, int nDuration, int nParam3 )Parameters
nPartyId (int) — id of the party whose screens to shake (usually room0.party_id — the party of the current room/instant zone).
nIntensity (int) — shake intensity: the bigger, the more noticeably the picture sways (10, 20 in the calls).
nDuration (int) — shake duration (10 in the calls).
nParam3 (int) — extra client-side shake effect setting (1 in the calls).Example
EarthQuakeToParty( room0.party_id, 20, 10, 1 );
EarthQuakeToParty( room0.party_id, 10, 10, 1 );RegisterAsOlympiadOperatorNPC🟢 high
Marks this NPC as an Olympiad operator — registration and match viewing go
through it. No arguments, called on myself once in the creation handler.
Signature
RegisterAsOlympiadOperator( )Parameters
(none — the function is called without arguments)Example
RegisterAsOlympiadOperator();GetOlympiadModeNPC🟢 high
The operator's main gate: returns [bool_pch] (@TRUE/@FALSE) — whether the Olympiad
registration/period is currently active. No arguments, on myself; nearly all dialog logic is wrapped in
a == @TRUE check.
Signature
GetOlympiadMode( )Parameters
(none — the function is called without arguments)Example
if (GetOlympiadMode() == @TRUE)Usage example
if (GetOlympiadMode() == @TRUE)
{
AddClassFreeOlympiad(talker);
}GetOlympiadStepNPC🟢 high
Returns the current phase of the Olympiad cycle as an integer. No arguments, on myself,
read-only.
Signature
GetOlympiadStep( )Parameters
(none — the function is called without arguments)Example
FHTML_SetInt(fhtml0, "olympiad_week", GetOlympiadStep());GetOlympiadSeasonNPC🟢 high
Returns the current Olympiad season number as an integer. No arguments, on myself,
read-only.
Signature
GetOlympiadSeason( )Parameters
(none — the function is called without arguments)Example
FHTML_SetInt(fhtml0, "olympiad_round", GetOlympiadSeason());GetOlympiadSeasonElapsedTimeNPC🟢 high
Returns as an integer how much time has already been counted since the start of the current
Olympiad season — that is, how long the current period has been running. The number is usually checked
to see whether enough has passed to allow a given action (for example, to show the results
or admit into a certain mode). No arguments, on myself, read-only.
Unit of measure is seconds: it returns the difference between the current time and the season
start time (0 if the season has not started yet).
Signature
GetOlympiadSeasonElapsedTime( )Parameters
(none — the function is called without arguments)Example
GetOlympiadSeasonElapsedTime( );GetOlympiadPlayerCountNPC🟢 high
Returns as an integer the exact number of players registered for the Olympiad at
the moment (the sum of everyone queued for matches). Suitable for showing "this many are
currently signed up" in a dialog. Note: stock scripts deliberately do not show this figure to
players (the output line was commented out) so that the exact participant count does not
provoke a mass simultaneous rush to register. No arguments, on myself,
read-only.
Signature
GetOlympiadPlayerCount( )Parameters
(none — the function is called without arguments)Example
FHTML_SetInt(fhtml0, "olympiad_participant", GetOlympiadPlayerCount());GetOlympiadWaitingCountNPC🟢 high
Returns as an integer how many players are waiting in the classed match queue.
No arguments, on myself, read-only.
Signature
GetOlympiadWaitingCount( )Parameters
(none — the function is called without arguments)Example
i0 = GetOlympiadWaitingCount();Usage example
i0 = GetOlympiadWaitingCount( );
if ( i0 < 100 ) {
FHTML_SetStr( fhtml0, "WaitingCount", MakeFString( 1000504, "100", _blank, _blank, _blank, _blank ) );
} else {
FHTML_SetStr( fhtml0, "WaitingCount", MakeFString( 1000505, "100", _blank, _blank, _blank, _blank ) );
}GetClassFreeOlympiadWaitingCountNPC🟢 high
Returns as an integer the size of the free-battle queue. No arguments,
on myself, read-only.
Signature
GetClassFreeOlympiadWaitingCount( )Parameters
(none — the function is called without arguments)Example
i0 = GetClassFreeOlympiadWaitingCount();Usage example
i0 = GetClassFreeOlympiadWaitingCount( );
if ( i0 < 100 ) {
FHTML_SetStr( fhtml0, "ClassFreeWaitingCount", MakeFString( 1000504, "100", _blank, _blank, _blank, _blank ) );
} else {
FHTML_SetStr( fhtml0, "ClassFreeWaitingCount", MakeFString( 1000505, "100", _blank, _blank, _blank, _blank ) );
}GetTeamOlympiadWaitingCountNPC🟢 high
Returns as an integer the size of the team-battle queue (3v3). No arguments,
on myself, read-only.
Signature
GetTeamOlympiadWaitingCount( )Parameters
(none — the function is called without arguments)Example
i0 = GetTeamOlympiadWaitingCount();Usage example
i0 = GetTeamOlympiadWaitingCount();
if (i0 < 100) {
FHTML_SetStr(fhtml0, "TeamWaitingCount", MakeFString(1000504, "100", _blank, _blank, _blank, _blank));
} else {
FHTML_SetStr(fhtml0, "WaitingCount", MakeFString(1000505, "100", _blank, _blank, _blank, _blank));
}GetOlympiadFieldIdNPC🟢 high
Returns as an integer the identifier of the Olympiad arena (field) to which this
NPC is bound. The number is usually saved to a variable and then substituted into functions for a specific
arena — for example, to learn the names of the fighters on it (GetPlayer1ForOlympiadField /
GetPlayer2ForOlympiadField take exactly this id). No arguments, on myself,
read-only.
Signature
GetOlympiadFieldId( )Parameters
(none — the function is called without arguments)Example
myself.i_ai0 = GetOlympiadFieldId();IsOlympiadRegisteredNPC🟢 high
Checks whether the player is already registered for a match; returns an integer (boolean).
Takes the player (talker, of type CSharedCreatureData), called on myself.
Signature
IsOlympiadRegistered( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose match registration is checkedExample
if (IsOlympiadRegistered(talker) == @FALSE)Usage example
if (IsOlympiadRegistered(talker) == @FALSE)
{
ShowPage(talker, "sf_antonius_proximo005.htm");
}
else
{
ShowPage(talker, "sf_antonius_proximo007.htm"); // You are already registered, do you want to cancel?
}AddOlympiadNPC🟢 high
Registers the player for a class one-on-one match (classed). Takes the player (talker,
of type CSharedCreatureData), on myself; before the call the logic checks the Olympiad mode,
the absence of registration, the level, and the profession.
Signature
AddOlympiad( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player registered for a class one-on-one matchExample
AddOlympiad(talker);Usage example
if ( GetOlympiadPoint( talker ) > 0 ) {
AddOlympiad( talker );
} else {
ShowPage( talker, "olympiad_operator010i.htm" );
}AddClassFreeOlympiadNPC🟢 high
Registers the player for a free one-on-one match without regard to class. Takes the player
(talker, of type CSharedCreatureData), on myself; the same preliminary checks as
the other Adds.
Signature
AddClassFreeOlympiad( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player registered for a free match without regard to classExample
AddClassFreeOlympiad(talker);Usage example
if ( GetOlympiadPoint( talker ) > 0 ) {
AddClassFreeOlympiad( talker );
} else {
ShowPage( talker, "olympiad_operator010i.htm" );
}AddBo3OlympiadNPC🟢 high
Registers the player for a best-of-3 match (up to two wins). Takes the player (talker,
of type CSharedCreatureData), on myself.
Signature
AddBo3Olympiad( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player registered for a best-of-3 matchExample
AddBo3Olympiad(talker);AddTeamOlympiadNPC🟢 high
Registers the player for a three-on-three team match. Takes the player (talker,
of type CSharedCreatureData), on myself.
Signature
AddTeamOlympiad( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player registered for a three-on-three team matchExample
AddTeamOlympiad(talker);Usage example
if ( GetOlympiadPoint( talker ) > 0 ) {
AddTeamOlympiad( talker );
} else {
ShowPage( talker, "olympiad_operator010i.htm" );
}RemoveOlympiadNPC🟢 high
Cancels the player's match registration (the "Cancel Registration" menu item). Takes the player
(talker, of type CSharedCreatureData), on myself.
Signature
RemoveOlympiad( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose match registration is cancelledExample
RemoveOlympiad(talker);EscapeOlympiadNPC🟢 high
Makes the player leave the Olympiad (exit). Takes the player (talker,
of type CSharedCreatureData), on myself.
Signature
EscapeOlympiad( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player who is taken out of the Olympiad
Example (illustrative):
EscapeOlympiad( talker );ShowOlympiadMatchListNPC🟢 high
Opens for the player the list of current battles (the "Watch Match" menu item). Takes the player
(talker, of type CSharedCreatureData), on myself.
Signature
ShowOlympiadMatchList( CSharedCreatureData pCreatureShared )Parameters
pCreatureShared (CSharedCreatureData) — the player who is shown the list of current battlesExample
ShowOlympiadMatchList(talker);Usage example
if ( ask == -1 && reply == 1 ) {
ShowOlympiadMatchList( talker );
}ObserveOlympiadNPC🟢 high
Sends the player as an observer to the chosen arena. Takes the player (talker,
of type CSharedCreatureData) and the arena identifier nFieldId, on myself.
Signature
ObserveOlympiad( CSharedCreatureData cCreature, int nFieldId )Parameters
cCreature (CSharedCreatureData) — the player sent as an observer.
nFieldId (int) — the identifier of the arena to observe. In calls it arrives from the menu reply
(the number of the chosen arena from the HTML battle list).Example
ObserveOlympiad( talker, reply );Usage example
if (ask == -130) {
ObserveOlympiad( talker, reply );
}GetPlayer1ForOlympiadFieldNPC🟢 high
Returns as a string the name of the first of the two fighters battling on the specified arena. Needed
to display the list of current duels to an observer — the name is inserted directly into the dialog
text next to the opponent's name (given by the paired GetPlayer2ForOlympiadField). If
there is no battle on the arena, an empty string is returned. Takes the arena identifier (taken from
GetOlympiadFieldId or iterated by arena numbers), on myself.
Signature
GetPlayer1ForOlympiadField( int field_id )Parameters
field_id (int) — the identifier of the arena whose first fighter is requestedExample
s0 = "&$1718;" + " " + GetPlayer1ForOlympiadField(i0) + " " + GetPlayer2ForOlympiadField(i0);GetPlayer1ForOlympiadFieldExNPC🟢 high
Returns the first fighter of the specified arena as a creature object (CSharedCreatureData).
Takes the arena identifier nFieldId, on myself.
Signature
GetPlayer1ForOlympiadFieldEx( int field_id )Parameters
field_id (int) — the identifier of the arena whose first fighter is requested (as a creature object)Example
c0 = GetPlayer1ForOlympiadFieldEx(event_id);GetPlayer2ForOlympiadFieldNPC🟢 high
Returns as a string the name of the second of the two fighters on the specified arena — the opponent of the one whose
name is given by GetPlayer1ForOlympiadField. In pair with it, used for the duel line
"fighter1 : fighter2" in the list of current battles for an observer. If there is no battle on the arena, an empty
string is returned. Takes the arena identifier (from GetOlympiadFieldId or by iterating over
arena numbers), on myself.
Signature
GetPlayer2ForOlympiadField( int field_id )Parameters
field_id (int) — the identifier of the arena whose second fighter is requestedExample
s0 = "&$1718;" + " " + GetPlayer1ForOlympiadField(i0) + " " + GetPlayer2ForOlympiadField(i0);GetPlayer2ForOlympiadFieldExNPC🟢 high
Returns the second fighter of the specified arena as a creature object (CSharedCreatureData).
Takes the arena identifier nFieldId, on myself.
Signature
GetPlayer2ForOlympiadFieldEx( int field_id )Parameters
field_id (int) — the identifier of the arena whose second fighter is requested (as a creature object)Example
c1 = GetPlayer2ForOlympiadFieldEx(event_id);GetOlympiadPointNPC🟢 high
Returns as an integer the player's current Olympiad points. Takes the player (talker,
of type CSharedCreatureData), on myself.
Signature
GetOlympiadPoint( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose current Olympiad points are requestedExample
if (GetOlympiadPoint(c0) > 0)Usage example
if ( GetOlympiadPoint( talker ) > 0 ) {
AddClassFreeOlympiad( talker );
} else {
ShowPage( talker, "olympiad_operator010i.htm" );
}GetPreviousOlympiadPointNPC🟢 high
Returns as an integer the player's points for the previous Olympiad period. Takes the player
(talker, of type CSharedCreatureData), on myself.
Signature
GetPreviousOlympiadPoint( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose points for the previous Olympiad period are requestedExample
/* if (GetPreviousOlympiadPoint(talker) < 50)Usage example
if (GetPreviousOlympiadPoint(talker) == 0 || GetOlympiadTradePoint(talker) == 0)
{
ShowPage(talker, "olympiad_operator_basic014.htm");
}
else
{
ShowPage(talker, "olympiad_operator_basic013.htm");
}GetOlympiadWinCountNPC🟢 high
Returns as an integer the player's number of Olympiad wins. Takes the player
(talker, of type CSharedCreatureData), on myself.
Signature
GetOlympiadWinCount( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the player whose number of Olympiad wins is requested
Example (illustrative):
GetOlympiadWinCount( talker );GetOlympiadTradePointNPC🟢 high
Returns as an integer the player's "trade" points — the currency for rewards. Takes the player
(talker, of type CSharedCreatureData), on myself.
Signature
GetOlympiadTradePoint( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose trade points are requestedExample
i0 = GetOlympiadTradePoint( talker );Usage example
if ( GetOlympiadTradePoint( talker ) > 0 ) {
DeleteOlympiadTradePoint( talker, GetOlympiadTradePoint( talker ) );
}AddOlympiadTradePointNPC🟢 high
Credits the player with Olympiad trade points — the currency for which rewards are then taken.
The second argument is simply how many points to add (an ordinary number, not a constant). A direct
pair to DeleteOlympiadTradePoint (deduction) and to GetOlympiadTradePoint (current balance):
one credits, another deducts, the third shows the balance. Takes the player and the number of
points, on myself.
Signature
AddOlympiadTradePoint( CSharedCreatureData cCreature, int nPoint )Parameters
cCreature (CSharedCreatureData) — the player credited with trade points
nPoint (int) — how many trade points to add (an ordinary number, not an enum)
Example (illustrative):
AddOlympiadTradePoint( talker, nPoint );DeleteOlympiadTradePointNPC🟢 high
Deducts the player's Olympiad trade points (the reward currency) — a pair to
AddOlympiadTradePoint. The second argument is how much to deduct; in practice
GetOlympiadTradePoint(talker) is passed, that is, the whole balance is zeroed at once (usually before giving
a reward for all accumulated points). It is reasonable to precede it with a GetOlympiadTradePoint(talker)
> 0 check, so as not to deduct from an empty balance. Takes the player and the number of points, on myself.
Signature
DeleteOlympiadTradePoint( CSharedCreatureData cCreature, int nPoint )Parameters
cCreature (CSharedCreatureData) — the player from whom trade points are deducted
nPoint (int) — how many trade points to deduct (usually GetOlympiadTradePoint(talker) — deduct all; not an enum)Example
DeleteOlympiadTradePoint( talker, i0 );
DeleteOlympiadTradePoint( talker, GetOlympiadTradePoint( talker ) );Usage example
if ( GetOlympiadTradePoint( talker ) > 0 ) {
DeleteOlympiadTradePoint( talker, GetOlympiadTradePoint( talker ) );
}
Related event: the server's response arrives as the DELETE_OLYMPIAD_TRADE_POINT_RETURNED event (see NASC_HANDLERS).DeletePreviousOlympiadPointNPC🟢 high
Deducts the player's points accumulated over the previous (already finished) Olympiad period —
they are exchanged for a reward at the end of the period separately from the current trade points. The second
argument is how much to deduct; in practice GetPreviousOlympiadPoint(talker) is passed,
that is, the whole previous balance is taken at once when giving the reward. Takes the player and the
number of points, on myself.
Signature
DeletePreviousOlympiadPoint( CSharedCreatureData cCreature, int nPoint )Parameters
cCreature (CSharedCreatureData) — the player from whom the previous period's points are deducted
nPoint (int) — how many previous-period points to deduct (usually GetPreviousOlympiadPoint(talker) — deduct all; not an enum)Example
DeletePreviousOlympiadPoint(talker, GetPreviousOlympiadPoint(talker));
Related event: the server's response arrives as the DELETE_PREVIOUS_OLYMPIAD_POINT_RETURNED event (see NASC_HANDLERS).GetNameByOlympiadRankOrderNPC🟢 high
Returns as a string the name of the fighter standing at the N-th place in the ranking ("hall of fame") of the chosen
class. The first argument is which class we look at (in dialogs it is taken from the player's choice,state/reply), the second — the ranking row number (1, 2, 3, …). The function fills the
ranking table: in a loop it iterates over places and at each one gets the name, points (GetPointByOlympiadRankOrder),
and rank (GetRankByOlympiadRankOrder). When the places run out, GetRankByOlympiadRankOrder at
that number returns 0 — and it is by this that the iteration is broken. On myself.
Signature
GetNameByOlympiadRankOrder( int nClassId, int nOrder )Parameters
nClassId (int) — the class by whose ranking the fighter is searched (usually from the player's choice in the dialog)
nOrder (int) — the place number in the class ranking (1 — first place, etc.)Example
FHTML_SetStr(fhtml0, "Name" + i0, GetNameByOlympiadRankOrder(state, i0));GetPointByOlympiadRankOrderNPC🟢 high
Returns as an integer the points of the fighter standing at the N-th place in the chosen class's ranking.
Fully paired with GetNameByOlympiadRankOrder and GetRankByOlympiadRankOrder — the same two
arguments and the same way of use: in a loop over places it gets the name, points, and rank, to
fill the ranking table. The first argument is which class we look at (in dialogs from the player's
choice), the second — the place number. On myself.
Signature
GetPointByOlympiadRankOrder( int nClassId, int nOrder )Parameters
nClassId (int) — the class by whose ranking the fighter is searched (usually from the player's choice in the dialog)
nOrder (int) — the place number in the class ranking (1 — first place, etc.)
Example (illustrative):
GetPointByOlympiadRankOrder( nClassId, nOrder );GetRankByOlympiadRankOrderNPC🟢 high
Returns as an integer the rank of the fighter standing at the N-th place in the chosen class's ranking.
A double purpose: on the one hand it gives the rank value for the table row, on the other —
it serves as an end-of-list marker. As long as someone is at the given place, it returns a rank > 0;
as soon as the places run out, it returns 0 — and it is by this zero that the iteration over places is broken. A pair to
GetNameByOlympiadRankOrder and GetPointByOlympiadRankOrder, the arguments are the same: the first — which
class we look at (in dialogs from the player's choice), the second — the place number. On myself.
Signature
GetRankByOlympiadRankOrder( int nClassId, int nOrder )Parameters
nClassId (int) — the class by whose ranking the fighter is searched (usually from the player's choice in the dialog)
nOrder (int) — the place number in the class ranking (1 — first place, etc.)Example
if (GetRankByOlympiadRankOrder(state, i0) > 0)Usage example
if (GetRankByOlympiadRankOrder(reply, i0) == 0) {
break;
}GetOlympiadTeamIdNPC🟢 high
Returns as an integer the number of the team the player fights for in a team (3v3)
Olympiad battle. Needed to distinguish friend from foe on the arena: the player's number is compared
with the team number assigned to a specific side of the field, and thus it is decided whether it is a friend or
an opponent. Outside a team battle the player has no meaningful team. Takes the player,
on myself.
Signature
GetOlympiadTeamId( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the player (fighter) whose team number is requestedExample
if (GetOlympiadTeamId(talker) == myself.i_ai1)AddTournamentNPC🟢 high
Registers the player for a specific tournament match (the tournament is a subsystem parallel to the Olympiad).
Takes the player (talker) and the registration code, on myself. The second
argument is NOT a "type/category", but the code of the target match, and it depends on the stage:
- At the group stage (when IsTournamentGroupStage() == @TRUE) zero is passed —
this is auto-registration for the current group match: AddTournament(talker, 0).
- In the finals (a non-group stage) the player enters the match code in the "Enter Code" dialog,
and this code (arrived as reply) is passed as the second argument:
AddTournament(talker, reply).
Before registration it is checked that the tournament is running at all — IsTournamentEnable() == @TRUE.
Related: IsTournamentGroupStage (group/finals), ShowTournamentMatchList
(the match window for viewing), GetTournamentNpcFlagId, AddBo3Olympiad
(registration for the Olympiad "best of three").
Signature
AddTournament( CSharedCreatureData c, int nRegisterCode )Parameters
c (CSharedCreatureData) — the player being registered
nRegisterCode (int) — the target match code: 0 = group auto-entry; in the finals — the code entered by the playerUsage example
if ( IsTournamentEnable() == @TRUE ) {
if ( IsTournamentGroupStage() == @TRUE ) { AddTournament( talker, 0 ); }
}
// finals, the "Registration to Match (Enter Code)" item:
if ( IsTournamentGroupStage() == @FALSE ) { AddTournament( talker, reply ); }ObserveTournamentNPC🟢 high
Sends the player as an observer to a tournament arena. Takes the player (talker,
of type CSharedCreatureData) and the arena identifier nFieldId, on myself.
Signature
ObserveTournament( CSharedCreatureData c, int nFieldId )Parameters
c (CSharedCreatureData) — the player sent as an observer to the tournament arena
nFieldId (int) — the identifier of the tournament arena to observe
Example (illustrative):
ObserveTournament( talker, nFieldId );ShowTournamentMatchListNPC🟢 high
Opens for the player the list of current tournament battles. Takes the player (talker,
of type CSharedCreatureData), on myself.
Signature
ShowTournamentMatchList( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the player who is shown the list of current tournament battlesExample
ShowTournamentMatchList(talker);GetTournamentNpcFlagIdNPC🟢 high
Returns as an integer the flag identifier of the tournament NPC. Takes the player (talker,
of type CSharedCreatureData), on myself.
Signature
GetTournamentNpcFlagId( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the player for whom the tournament NPC's flag identifier is requestedExample
GetTournamentNpcFlagId( talker );GetSpawnDefineMAKER🟢 high
Returns the maker's spawn define by index (from zero to the number of defines minus one). Argument nIndex (int) — the define number; called on myself ([CNpcMakerEx]). The result is checked for null via IsNull. Returns a [CNpcSpawnDefineEx] object.
Signature
GetSpawnDefine( int nIndex )Parameters
nIndex (int) — index of the spawn define (from zero to the number of defines minus one).Example
def0 = GetSpawnDefine(i0);Usage example
def0 = GetSpawnDefine( i0 );
if ( IsNull( def0 ) == 0 ) {
def0.Despawn( );
}GetSpawnDefineByNickMAKER🟢 high
Returns the maker's spawn define by its nick (the define's name field). Argument sNick (string) — the nick of the define being searched for; called on myself ([CNpcMakerEx]). The result is checked for null via IsNull. Returns a [CNpcSpawnDefineEx] object.
Signature
GetSpawnDefineByNick( string sNick )Parameters
sNick (string) — nick (name) of the spawn define being searched for.Example
def0 = GetSpawnDefineByNick(manager_npc_name);AtomicIncreaseTotalMAKER🟢 high
Atomically increases the maker's planned spawn count (total) by the given number (under a lock, clamped to the range [0, maximum]). This is protection against a race: until one handler finishes its reservation, another cannot cut in. Returns NOT one, but the current total value after the operation (zero means the increment went out of bounds or deduplication skipped the increment); scripts use the result as a truthy "spawning allowed" flag. Arguments: def ([CNpcSpawnDefineEx]) — the define whose plan is increased; nCount (int) — the increment amount (often the whole total or one unit); the third argument is NOT a "step" but a uniqueness flag: with value 1 deduplication is enabled and each define is counted only once (protection against double counting), with 0 the increment always applies. Called on myself ([CNpcMakerEx]).
Signature
AtomicIncreaseTotal( CNpcSpawnDefineEx def, int nCount, int bUnique )Parameters
def (CNpcSpawnDefineEx) — the define whose planned total is increased.
nCount (int) — the amount added to the planned count (often the whole total or 1).
bUnique (int) — uniqueness flag: 1 = count the define once (dedup), 0 = always add.Example
if (AtomicIncreaseTotal(def0, i1, 1))Usage example
if (AtomicIncreaseTotal(def0, def0.total, 1)) {
def0.Spawn2(def0.total, 0, 0);
}DoRespawnMAKER🟢 high
Executes the maker's accumulated deferred respawns; usually triggered by a timer. Takes no arguments; called on myself ([CNpcMakerEx]).
Signature
DoRespawn( )Parameters
(none — the function is called without arguments)Example
DoRespawn();Usage example
if (myself.i_ai0 == 1) {
DoRespawn();
AddTimerEx(5001, 1000);
}ResetRespawnMAKER🟢 high
Resets (clears) the maker's queue of deferred respawns. Takes no arguments; called on myself ([CNpcMakerEx]).
Signature
ResetRespawn( )Parameters
(none — the function is called without arguments)Example
ResetRespawn();RegisterRespawnMAKER🟢 high
Enqueues a deferred respawn: a given number of specimens of the define after a given delay; usually called when an NPC is deleted. Arguments: nRespawnTime (int) — delay until the respawn; nCount (int) — how many to respawn (one everywhere); def ([CNpcSpawnDefineEx]) — which define to respawn. Called on myself ([CNpcMakerEx]).
Signature
RegisterRespawn( int nRespawnTime, int nCount, CNpcSpawnDefineEx def )Parameters
nRespawnTime (int) — delay until the deferred respawn (usually deleted_def.respawn_time).
nCount (int) — how many specimens to respawn (one everywhere).
def (CNpcSpawnDefineEx) — the spawn define that must be respawned.Example
RegisterRespawn( i4, 1, deleted_def );
RegisterRespawn(deleted_def.respawn_time, 1, deleted_def);Usage example
if (myself.i_ai0 == 1 && deleted_def.respawn_time != 0) {
RegisterRespawn(deleted_def.respawn_time, 1, deleted_def);
}RegisterOlympiadFieldEventExMAKER🟢 high
Subscribes the maker (spawner) to Olympiad arena events so that it receives notifications
about the field's lifecycle — phase changes, match preparation, stage changes — and uses them
to place/remove fighters and decorations. Called once during maker initialization; after that
it reacts to arena events. No arguments, called on the maker.
Signature
RegisterOlympiadFieldEventEx( )Parameters
(none — the function is called without arguments)Example
RegisterOlympiadFieldEventEx();
Related event: subscribes the maker to Olympiad arena events — ON_OLYMPIAD_FIELD_CHANGED (phase change), ON_OLYMPIAD_GAME_PREPARED (match prepared), ON_OLYMPIAD_FIELD_STEP_CHANGED_EVENT (field stage change) (see NASC_HANDLERS).Teleport and position (Teleport / Position)
25 functionsGetRandomPosInCreatureGLOBAL🟢 high
Returns a random position (an object with x/y/z fields) around the creature c at a distance from nMinDistance to nMaxDistance. This is a typical way to pick a point near a player for spawning, teleporting, or scattering helpers. Belongs to the global object; takes a creature c (CSharedCreatureData), nMinDistance (int), and nMaxDistance (int), returns a CPosition.
Signature
GetRandomPosInCreature( CSharedCreatureData cCreature, int nMinDistance, int nMaxDistance )Parameters
cCreature (CSharedCreatureData) — around whom.
nMinDistance (int) — min. radius.
nMaxDistance (int) — max. radius.Example
pos0 = GetRandomPosInCreature(c0, 10, 40);GetRandomPosInPosGLOBAL🟢 high
Returns a random position around the point x, y in a ring of radii from nMinDistance to
nMaxDistance (takes a random radius and angle). The function does NOT set the Z height manually — it always
snaps it to the terrain (geodata). The bIsFloating flag goes into the visibility/passability check:
one allows "floating"/aerial points (for flying NPCs, over water/void), zero
requires normally reachable ground. Makes up to five attempts to find a valid point; if they all
fail — returns the original point unchanged. Returns a CPosition.
Signature
GetRandomPosInPos( int nX, int nY, int nZ, int bIsFloating, int nMinDistance, int nMaxDistance )Parameters
nX (int) — the X coordinate of the center around which a random position is searched
nY (int) — the Y coordinate of the center around which a random position is searched
nZ (int) — the Z coordinate of the center around which a random position is searched
bIsFloating (int) — flag for accounting for the "floating" (aerial) height when picking a position
nMinDistance (int) — the minimum radius of the ring within which the random position is picked
nMaxDistance (int) — the maximum radius of the ring within which the random position is pickedExample
pos0 = GetRandomPosInPos(-209282, -53031, -12295, @FALSE, 20, 350);GetRandomPosInTerritoryGLOBAL🟢 high
Returns a random point inside a named territory; nIsFlying sets whether the position should be flying. Belongs to the global object; takes sTerritoryName (string) and nIsFlying (int), returns a CPosition.
Signature
GetRandomPosInTerritory( string pwsTerritoryName, int nIsFlying )Parameters
pwsTerritoryName (string) — the name of the territory inside which a random point is picked
nIsFlying (int) — flag for whether the returned position should be flying (aerial)Example
pos0 = GetRandomPosInTerritory(TRR_STAR, 0);GetRandomPosInTerritory2GLOBAL🟢 high
Picks a random point inside a named territory — convenient for scattering a spawn or
setting wandering without writing coordinates by hand. The territory is given by name and must be
declared in npcpos.txt; if it is not found, the function returns nothing and logs it. The
nIsFlying argument says whether to take a point "in the air" (for flying creatures) or on the ground. The third
argument is a label string that the engine calls the "AI name": it is used ONLY in the
log message when the territory is not found and does NOT affect point selection itself. Returns a ready
position (CPosition), from which x/y/z is then taken.
Signature
GetRandomPosInTerritory2( string pwsTerritoryName, int nIsFlying, string pwsAiName )Parameters
pwsTerritoryName (string) — the name of the territory (declared in npcpos.txt) inside which a random point is taken.
nIsFlying (int) — take the point in the air (for flying, 1) or on the ground (0).
pwsAiName (string) — a label for the log (the calling AI's name); participates only in the error message, does not affect point selection.
Example (illustrative):
GetRandomPosInTerritory2( "", nIsFlying, "" );InstantTeleportNPC🟢 high
Instantly moves creature c to the given point of the game world. Takes a creature
(CSharedCreatureData) and three integer coordinates x, y, z; the arguments have no
namespace, and there is no return value. The most common teleport: take a player or their
summon (via attacker.master) out of combat or a zone, deliver them to an event site;
works on anyone — talker, attacker, any creature.
Signature
InstantTeleport( CSharedCreatureData cCreature, int x, int y, int z )Parameters
cCreature (CSharedCreatureData) — who to teleport.
x (int) — destination X coordinate.
y (int) — Y coordinate.
z (int) — Z coordinate.Example
InstantTeleport( myself.sm, i0, i1, i2 );Usage example
if (GetPathfindFailCount() > 10 && speller == myself.top_desire_target && FloatToInt(myself.sm.hp) != FloatToInt(myself.sm.max_hp)) {
InstantTeleport(myself.sm, FloatToInt(speller.x), FloatToInt(speller.y), FloatToInt(speller.z));
}InstantTeleportInMyTerritoryNPC🟢 high
Mass teleport: moves all creatures located on the territory assigned to the NPC
to the point nPosX, nPosY, nPosZ with scatter within radius nRadius around the destination
point. All four arguments are integers, no namespace, returns no
value. This is how raid bosses gather players or, conversely, throw them out of the zone when
resetting a fight.
Signature
InstantTeleportInMyTerritory( int nPosX, int nPosY, int nPosZ, int nRadius )Parameters
nPosX (int) — destination X.
nPosY (int) — destination Y.
nPosZ (int) — destination Z.
nRadius (int) — scatter radius/area (to be clarified).Example
InstantTeleportInMyTerritory(f8_x, f8_y, f8_z, 500);Usage example
if ( myself.sm.db_value == 0 && myself.sm.alive == 1 ) {
InstantTeleportInMyTerritory( 80464, 152294, -3534, 100 );
}InstantTeleportInMyTerritory2NPC🟢 high
The second variant of "gathering" creatures across the NPC's territory: moves everyone currently on
the territory assigned to the NPC at once to the point (x, y, z), spreading them not into a single cell but with
scatter within nRadius around it so the crowd does not clump into one spot. Often
called in a chain via switch — each case gets its own destination point; this is how players are
repositioned between combat phases or platforms. Returns nothing. Differs from the version without "2"
only in the subtlety of picking the final point (a walkability check); for the scripter
the behavior and all four arguments are identical.
Signature
InstantTeleportInMyTerritory2( int nPosX, int nPosY, int nPosZ, int nRadius )Parameters
nPosX (int) — X of the point where to gather creatures.
nPosY (int) — destination Y.
nPosZ (int) — destination Z.
nRadius (int) — scatter radius around the point: creatures are spread within it so they do not clump.Example
InstantTeleportInMyTerritory2(-19480, 187344, -5600, 200);InstantRandomTeleportInMyTerritoryNPC🟢 high
Teleports the NPC to a random point of its territory without specifying coordinates — the engine
picks it itself. No arguments, no return value. Used for
"jerking" a mob around the zone.
Signature
InstantRandomTeleportInMyTerritory( )Parameters
(none — the function is called without arguments)Example
InstantRandomTeleportInMyTerritory();Usage example
if ( DBPosCheck == 1 && reply == 1 && InMyTerritory( myself.sm ) == 0 ) {
InstantRandomTeleportInMyTerritory( );
}TeleportToNPC🟢 high
Teleports creature pTarget1 to the position of creature pTarget2 — pulls one to the
other without specifying explicit coordinates. Takes two creatures (CSharedCreatureData),
no namespace, returns no value. Convenient to gather a target to an anchor.
Signature
TeleportTo( CSharedCreatureData pTarget1, CSharedCreatureData pTarget2 )Parameters
pTarget1 (CSharedCreatureData) — who is being moved.
pTarget2 (CSharedCreatureData) — to whom (destination = their position).Example
TeleportTo(myself.sm, myself.c_ai0);
TeleportTo( attacker, attacker.master );
TeleportTo(attacker.master, attacker.master);TeleportToUserNPC🟢 high
A TeleportTo variant aimed at moving creature c1 to player c2 (for example,
summoning an NPC or a pet to its owner). Takes two creatures (CSharedCreatureData),
no namespace, returns no value. The exact difference from TeleportTo is unconfirmed.
Signature
TeleportToUser( CSharedCreatureData c, CSharedCreatureData cUser )Parameters
c (CSharedCreatureData) — who is being moved.
cUser (CSharedCreatureData) — to which player (destination = their position).Example
TeleportToUser(talker, c0);
Related event: the server response arrives via the TELEPORT_TO_USER_RES event (see NASC_HANDLERS).TeleportNPC🟢 high
The classic city teleport gatekeeper: shows the player a list of destinations
telPosList (type CTelPosList) with labels and transfers by choice. Per the L2NPC decompile
(CNPC::Teleport_4885D0) the window is sent to the server via an opcode 7 packet of format "cdddSSSSdSd":
after the service fields come four window label strings, the currency item id and its
display name. The first label string is the title/shop name (ShopName), the other three
are usually empty; the second-to-last argument is the payment currency from [item_pch] (@adena=57 in the calls),
the last one is its name for display ("Adena"). Returns no value. There is an extension
TeleportFStr with localized NPC-string labels.
Signature
Teleport( CSharedCreatureData c, CTelPosList telPosList, string sTitle, string sLabel2, string sLabel3, string sLabel4, int nCurrencyItemId, string sCurrencyName )Parameters
c (CSharedCreatureData) — player.
telPosList (CTelPosList) — list of destinations.
sTitle (string) — title/name of the teleport window (ShopName).
sLabel2 (string) — extra window label (usually "" / _blank).
sLabel3 (string) — extra window label (usually "" / _blank).
sLabel4 (string) — extra window label (usually "" / _blank).
nCurrencyItemId (int) — payment currency item (@adena = 57 in the calls).
values — from the [item_pch] dictionary
sCurrencyName (string) — display name of the currency ("Adena").Example
Teleport( talker, PositionPrimeHours, ShopName, _blank, _blank, _blank, @adena, "Adena" );
Teleport( talker, Position1, ShopName, _blank, _blank, _blank, 57, _blank );
Teleport( talker, Position2, ShopName, _blank, _blank, _blank, 57, _blank );
Teleport( talker, PositionPrimeHours, ShopName, "", "", "", 57, "Adena" );Usage example
if ( reply == 3 ) {
Teleport( talker, Position3, ShopName, "", "", "", 57, MakeFString( 1000308, "", "", "", "", "" ) );
}TeamInstantTeleportNPC🟢 high
Teleports an event team (by nEventId and nTeamId) to the point x, y, z — for PvP and
event arenas, to disperse teams to their starting positions. All five arguments are
integers, no namespace; returns a result (number transferred or a code). There is a
strict version TeamInstantTeleportWithConditions with checks and exclusion of
unsuitable participants.
Signature
TeamInstantTeleport( int nEventId, int nTeamId, int nX, int nY, int nZ )Parameters
nEventId (int) — event id.
nTeamId (int) — team id.
nX (int) — X coordinate of the point where the team is teleported
nY (int) — Y coordinate of the point where the team is teleported
nZ (int) — Z coordinate of the point where the team is teleportedExample
TeamInstantTeleport(my_Event, 1, 147574, 46717, -3400);
TeamInstantTeleport(my_Event, 1, Return_X, Return_Y, Return_Z );
TeamInstantTeleport(my_Event, 2, Return_X, Return_Y, Return_Z );
TeamInstantTeleport(my_Event, 2, 151496, 46717, -3400);Usage example
if ( TeamEventGetStatus( my_Event ) == @TEAMEVENT_STATUS_BATTLE ) { // if the event is in battle mode and players are on the arena
TeamInstantTeleport( my_Event, 1, Return_X, Return_Y, Return_Z );
TeamInstantTeleport( my_Event, 2, Return_X, Return_Y, Return_Z );
InstantTeleportInMyTerritory( Return_X, Return_Y, Return_Z, 50 );
}TeleportPartyNPC🟢 high
Teleports party members to the point x, y, z. Per the L2NPC decompile it assembles an atomic-job
and sends the server an opcode 14 packet; the handler (L2Server: AtomicTeleportParty::Do_44BF5C) takes
the party leader's position and iterates over all members. The fifth argument is a filter by distance from
the leader: if 0 — ALL members are teleported; if greater than zero — only those who are within
that distance from the leader (in a straight line). The sixth argument is a private id that the server
assigns to each teleported member (CCreature::SetPrivateID). Returns 1.
Signature
TeleportParty( int nPartyId, int x, int y, int z, int nMaxDistFromLeader, int nPrivateId )Parameters
nPartyId (int) — id of the party being teleported (party0.id).
x (int) — destination X coordinate.
y (int) — destination Y coordinate.
z (int) — destination Z coordinate.
nMaxDistFromLeader (int) — 0 = teleport all members; >0 = only members within
this distance from the party leader (0 in the calls).
nPrivateId (int) — private id assigned to each teleported member (0 in the calls).Example
TeleportParty( party0.id, 113600, -126170, -3512, 0, 0 );InstantTeleportWithItemNPC🟢 high
Teleport for a fee: moves creature c to the point x, y, z, deducting nCount pieces
of item nItemClassId. Takes a creature, three integer coordinates, the identifier
of the payment item [item_pch] and the count (int64); returns no value. A paid
teleporter.
Signature
InstantTeleportWithItem( CSharedCreatureData c, int x, int y, int z, int nItemClassId, int64 nCount )Parameters
c (CSharedCreatureData) — who to teleport.
x (int) — destination X coordinate.
y (int) — destination Y coordinate.
z (int) — destination Z coordinate.
nItemClassId (int) — payment item for the teleport.
values — from the [item_pch] dictionary
nCount (int64) — quantity of the payment item to deduct.Example
InstantTeleportWithItem(talker, -80684, 149770, -3043, ItemNeeded, 1);
InstantTeleportWithItem(talker, -80749, 149834, -3043, ItemNeeded, 1);Usage example
if (OwnItemCount( talker, ItemNeeded ) != 0) {
InstantTeleportWithItem(talker, -80684, 149770, -3043, ItemNeeded, 1);
return;
} else {
ShowPage(talker, fnNoItem);
}SetTeleportPosOnLostNPC🟢 high
Sets the point x, y, z where the NPC teleports after losing its target (on aggro reset or
leaving the bounds). Takes three integer coordinates, no namespace, returns no
value. Analogous to returning to the spawn point — configures the leash behavior.
Signature
SetTeleportPosOnLost( int x, int y, int z )Parameters
x (int) — X coordinate of the return point on target loss.
y (int) — Y coordinate of the return point on target loss.
z (int) — Z coordinate of the return point on target loss.Example
SetTeleportPosOnLost( b03_x1, b03_y1, b03_z1 );
SetTeleportPosOnLost( b03_x2, b03_y2, b03_z2 );
SetTeleportPosOnLost( b03_x3, b03_y3, b03_z3 );
SetTeleportPosOnLost( b03_x4, b03_y4, b03_z4 );Usage example
if ( myself.i_ai0 == 1 && InMyTerritory( myself.sm ) == 0 ) {
SetTeleportPosOnLost( b03_x1, b03_y1, b03_z1 );
InstantTeleport( myself.sm, b03_x1, b03_y1, b03_z1 );
}DistFromMeNPC🟢 high
Returns the distance from this NPC to creature c. This is the main range-check tool — let the target approach or back off, whether it is within cast range, whether the target ran away; the result is compared with thresholds (less than three hundred, no more than fifteen hundred and so on). Takes creature c (CSharedCreatureData), returns float.
Signature
DistFromMe( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — who to measure the distance to.Example
f0 = DistFromMe( myself.c_ai1 );
f0 = DistFromMe( c0 );
f0 = DistFromMe(myself.c_quest0);Usage example
if ( IsNullCreature( myself.boss ) == 0 && DistFromMe( myself.boss ) > 500 && myself.boss.alive != 0 && myself.p_state != 3 ) {
InstantTeleport( myself.sm, FloatToInt( myself.boss.x ), FloatToInt( myself.boss.y ), FloatToInt( myself.boss.z ) );
}PointDistFromMeNPC🟢 high
Returns the distance from the NPC to an arbitrary point x, y, z rather than to a creature. Convenient for checking proximity to an anchor or a zone when there is no creature at that point. Takes three float coordinates, returns float.
Signature
PointDistFromMe( float x, float y, float z )Parameters
x (float) — X coordinate of the point to which the distance from the NPC is measured.
y (float) — Y coordinate of the point to which the distance from the NPC is measured.
z (float) — Z coordinate of the point to which the distance from the NPC is measured.Example
i6 = FloatToInt( PointDistFromMe( i7, i8, i9 ) );Usage example
if (PointDistFromMe(myself.start_x, myself.start_y, myself.start_z) > 10000)
{
InstantTeleport(myself.sm, myself.start_x, myself.start_y, myself.start_z);
}StaticObjectDistFromMeNPC🟢 high
Returns the distance from the NPC to a static object — a door, siege flag, artifact (an object of type CSharedStaticObjectData). Used in logic around doors and thrones. Takes obj (CSharedStaticObjectData), returns float.
Signature
StaticObjectDistFromMe( CSharedStaticObjectData obj )Parameters
obj (CSharedStaticObjectData) — static object (door/flag/artifact).Example
if ( StaticObjectDistFromMe( so0 ) >= 2500 ) {Usage example
if ( StaticObjectDistFromMe( so0 ) >= 2500 ) { SayFStr( 1110074, _blank, _blank, _blank, _blank, _blank ); } else
{
if ( Skill_InReuseDelay( DDMagic ) ) { SayFStr( 1010551, _blank, _blank, _blank, _blank, _blank ); }
if ( Skill_GetConsumeMP( DDMagic ) < myself.sm.mp && Skill_GetConsumeHP( DDMagic ) < myself.sm.hp && Skill_InReuseDelay( DDMagic ) == 0 ) {
AddUseSkillDesireExByAction(i0, DDMagic, 0, reply, ask, 1000000, 0, action_id);
}
}GetAngleFromTargetNPC🟢 high
Returns the angle to creature c relative to the NPC's orientation in client units (65536 = 360°). The AI uses it to determine the sector — front, side or back: for example, a range of roughly 36864..61440 (202°…337°) means the target is behind-to-the-side, which is needed for positional skills like a backstab. Takes creature c (CSharedCreatureData), returns int.
Signature
GetAngleFromTarget( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — relative to whom the angle is taken.Example
i0 = GetAngleFromTarget(creature);GetDirectionNPC🟢 high
Returns the direction (heading) from the NPC to creature c in client rotation units. Used to turn someone to face the right way or to set orientation when spawning helpers. Takes creature c (CSharedCreatureData), returns int.
Signature
GetDirection( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — who the direction points to.Example
i0 = GetDirection(myself.sm);
i1 = GetDirection( myself.sm );GetDirectionToTargetNPC🟢 high
Returns the direction (heading) from the NPC to creature c in client rotation units, like GetDirection; the exact difference between the two variants is unconfirmed (this one probably relates to the current aggro target). Takes creature c (CSharedCreatureData), returns int.
Signature
GetDirectionToTarget( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature whose direction (heading) is returnedExample
CreateOnePrivateEx( @event_its_pig, "ai_event_its_pig", 0, 0, FloatToInt( myself.sm.x ), FloatToInt( myself.sm.y ), FloatToInt( myself.sm.z ), (GetDirectionToTarget( myself.sm ) * 182), myself.i_ai0, 0, 0 );FindNeighborHeroNPC🟢 high
Searches within radius nDist for a character with Hero status and returns them (or null) for a special NPC reaction to the presence of heroes nearby. The result is usually checked via IsNull. Takes nDist (int), returns a creature (CSharedCreatureData).
Signature
FindNeighborHero( int nDist )Parameters
nDist (int) — search radius.Example
c3 = FindNeighborHero(4000);Usage example
c3 = FindNeighborHero( 4000 );
if ( IsNullCreature( c3 ) == 0 ) {
BroadcastOnScreenMsgFStr( myself.sm, 4000, 1, 0, 0, 0, 0, 0, 3000, 0, 1000519, c3.name, _blank, _blank, _blank, _blank );
}InstantTeleportMPCCNPC🟢 high
Teleports the members of the creature's command channel (MPCC) to the point x, y, z, distributing them around
it. Per the L2Server handler (NpcInstantTeleportMPCC → CMultiPartyCommandChannel::TeleportMPCCToLocation)
the server: takes the channel members, lays out landing points within the scatter radius around the target,
for each checks geodata and picks a ground level (FindGround with +200 on Z, a random
scatter ±60), and if a member is already within the radius — does not move it. The fourth argument is
the scatter radius (compared as radius² with the squared distance; in calls 1000/3000). The fifth and
sixth configure the layout of the landing points; with a given delay (int64 > 0) the teleport is performed
deferred. No return.
Signature
InstantTeleportMPCC( CSharedCreatureData c, int x, int y, int z, int nRadius, int nLayoutParam1, int nLayoutParam2, int nPrivateId, int64 nDelay )Parameters
c (CSharedCreatureData) — the creature by whose command channel the members are teleported.
x (int) — the X coordinate of the target point.
y (int) — the Y coordinate of the target point.
z (int) — the Z coordinate of the target point.
nRadius (int) — the scatter radius around the target: members are scattered within it, those already
inside — are not moved (in calls 1000, 3000).
nLayoutParam1 (int) — a landing-point layout parameter (in calls 0, 100, 200).
nLayoutParam2 (int) — a landing-point layout parameter (in calls 200, 300, 500).
nPrivateId (int) — the private id set on the teleported members (in calls 0, 57, 3865).
nDelay (int64) — the teleport delay: >0 enables a deferred teleport (in calls 0 — immediately).Example
InstantTeleportMPCC( talker, TelPosX, TelPosY, TelPosZ, 3000, 100, 200, 0, 0 );
InstantTeleportMPCC( talker, 179700, 113800, -7709, 1000, 200, 500, 3865, 0 );
InstantTeleportMPCC(talker, TelPosX, TelPosY, TelPosZ, 1000, 100, 200, 0, 0);
InstantTeleportMPCC( talker, 16342, 209557, -9352, 3000, 0, 300, 57, 0 );InstantTeleportInMyTerritoryWithConditionNPC🟢 high
Mass-moves creatures located on this NPC's territory to a given point.
Not everyone moves, but those selected by group membership: the pair (nType, nCondition)
sets the filter. A candidate is moved only if it is in the same instant zone as the NPC,
stands inside the NPC's territory, and falls within its height range. Returns nothing;
used in combat/team zones (towers, halls), to gather at once or, conversely,
to set out a group of players. The landing point is (x, y) with a random scatter within
nRadius (the ground is picked by the terrain).
Signature
InstantTeleportInMyTerritoryWithCondition( int x, int y, int z, int nRadius, int nType, int nCondition )Parameters
x (int) — the X coordinate of the target point.
y (int) — the Y coordinate of the target point.
z (int) — the Z coordinate of the target point (used as the reference height when searching for ground).
nRadius (int) — the radius of the random scatter around the point (in calls 200).
nType (int) — the group-selection mode (what meaning nCondition has):
1 — move ONLY members of the group with id = nCondition;
2 — move everyone on the territory EXCEPT members of the group with id = nCondition;
other — move everyone, nCondition is not taken into account.
nCondition (int) — the group id (party id) against which each candidate's membership is checked.
In the example this is myself.i_quest0, into which the player's group id was written in advance
(myself.i_quest0 = party0.id).Example
InstantTeleportInMyTerritoryWithCondition( 16110, 243841, 11616, 200, 2, myself.i_quest0 );
// (from c_tower_combat_manager: in advance myself.i_quest0 = party0.id — the id of the entered player's group;
// nType=2 → move everyone on the territory to the point, except this group)RenewSpawnedPosNPC🟢 high
Recomputes (updates) the spawn position, for example on revival. Takes the
coordinates x, y, z, usually taken from the NPC's own current position. Returns
nothing.
Signature
RenewSpawnedPos( int x, int y, int z )Parameters
x (int) — the new X coordinate of the spawn position.
y (int) — the new Y coordinate of the spawn position.
z (int) — the new Z coordinate of the spawn position.Example
RenewSpawnedPos(FloatToInt(myself.sm.x), FloatToInt(myself.sm.y), FloatToInt(myself.sm.z));Usage example
if (timer_id == 7777 && type == 1) {
RenewSpawnedPos(FloatToInt(myself.sm.x), FloatToInt(myself.sm.y), FloatToInt(myself.sm.z));
} else
if (timer_id == 7787) {
Despawn();
}INSTANCES AND ROOMS (InstantZone / Room)
14 functionsCreateRoomInfoListGLOBAL🟢 high
Creates a named container of rooms (a RoomInfoList) in the global table.
The first argument is the list name, the second is the capacity (how many rooms). Returns one
if the list was created, and zero if a list with that name already exists (see the example —
that is exactly why the result is checked against zero). Rooms are then addressed through the handler's local
slots (room0, rlist0, etc.).
Signature
CreateRoomInfoList( string sListName, int nCapacity )Parameters
sListName (string) — the name of the room list being created
nCapacity (int) — the list capacity (number of rooms)Example
i0 = CreateRoomInfoList(LevelName, 9);Usage example
i0 = CreateRoomInfoList(LevelName, 9);
if (i0 == 0) {
}InstantZone_GetNpcMakerGLOBAL🟢 high
Finds a maker inside an instance by the zone identifier and its name. Called
globally (gg); the arguments are the zone identifier (from InstantZone_GetId /
GetInZoneID) and the maker name; returns the maker object. The result is checked for
emptiness and then sent an event.
Signature
InstantZone_GetNpcMaker( int nInstZoneId, string sMakerName )Parameters
nInstZoneId (int) — the identifier of the zone inside which the maker is searched (InstantZone_GetId()/GetInZoneID())
sMakerName (string) — the name of the maker being searchedExample
maker0 = InstantZone_GetNpcMaker( i0, s0 );Usage example
maker0 = InstantZone_GetNpcMaker( InstantZone_GetId( ), "godard32_1713_103m1" );
if ( IsNull( maker0 ) == @FALSE ) { SendMakerScriptEvent( maker0, @SPAWN_ALL_INSTANT, 0, 0 ); }GetRoomInfoListGLOBAL🟢 high
Returns a level's list of "rooms" by its name. Called globally (gg);
the single argument is the level name; a room is a record of a party that has taken a slot
or a copy. From the list a room is taken by index, its fields are read (the party
identifier, the number of members, time, atomic state) and its members are iterated;
more about the room object is said in the objects file.
Signature
GetRoomInfoList( string sLevelName )Parameters
sLevelName (string) — the name of the level whose room list is requestedExample
rlist0 = GetRoomInfoList(LevelName);Usage example
rlist0 = GetRoomInfoList( LevelName );
if( IsNull( rlist0 ) ) {
AddTimerEx( timer_id, 10000 );
return;
}InstantZone_EnterNPC🟢 high
Sends a creature into a new instant zone of the given type. Called on the NPC (myself);
the arguments are the creature itself (talker), the zone type, and the enter type from
[manual_pch] (@eIZ_ET_*), which determines who gets pulled in: only the player himself,
his whole party, or the entire command channel (i.e. the raid). The zone type may be a raw
number, a named constant, or taken directly from the player's field — "the type he is
already using"; the latter is needed to re-enter one's own zone and is the most common case.
Returns nothing.
Related event: the reply arrives as the INSTANT_ZONE_ENTER_RETURNED event (see NASC_HANDLERS).
Signature
InstantZone_Enter( CSharedCreatureData c, int nZoneType, int nEnterType )Parameters
c (CSharedCreatureData) — who enters (talker).
nZoneType (int) — instant zone type (raw number, named constant, or the player's field — "his type").
nEnterType (int) — who to pull into the instant zone (manual_pch):
@eIZ_ET_ONLY_ME (0) — only the player himself; @eIZ_ET_ALL_PARTY (1) — his whole party;
@eIZ_ET_COMMAND_CHANNEL (2) — the entire command channel (raid).Example
InstantZone_Enter(talker, i0, @eIZ_ET_ONLY_ME);Usage example
if ( zone_type > -1 && enter_type > -1 ) {
InstantZone_Enter( talker, zone_type, enter_type );
}InstantZone_LeaveNPC🟢 high
Takes the specified creature out of the instant zone. Called on the NPC (myself); the only
argument is the creature itself. Returns nothing.
Signature
InstantZone_Leave( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature being taken out of the instant zoneExample
InstantZone_Leave(c0);Usage example
if ( ask == 23000 && reply == 1 ) {
InstantZone_Leave( talker );
}InstantZone_FinishNPC🟢 high
Finishes (closes) the current instant zone with a delay in seconds. Called on the NPC
(myself); the only argument is the delay before closing (0/5/10/15 in the scripts),
given so that players have time to leave or read a message. Returns nothing.
Signature
InstantZone_Finish( int nDelay )Parameters
nDelay (int) — delay before closing the instant zone, in secondsExample
InstantZone_Finish(5);Usage example
if ( InzoneRestriction == 1 || InzoneFinish == 1 ) {
InstantZone_Finish( 5 );
}InstantZone_GetIdNPC🟢 high
Returns the identifier of the current instant zone. Called on the NPC (myself), no
arguments; the obtained id is then passed to instant zone door control, to NPC spawning
inside the copy, and to zone maker lookup.
Signature
InstantZone_GetId( )Parameters
(none — the function is called without arguments)Example
i0 = InstantZone_GetId();
i2 = InstantZone_GetId();
i1 = InstantZone_GetId();
i4 = InstantZone_GetId( );Usage example
i2 = InstantZone_GetId( );
if ( c0.instant_zone_id == i2 ) {
AddMoveToDesire( FloatToInt( c0.x ), FloatToInt( c0.y ), FloatToInt( c0.z ), 100000000 );
}InstantZone_GetDurationNPC🟢 high
Activates lifetime tracking for the current instant zone — starts its duration timer.
Despite the name, it returns no value (void): in scripts it is called to start the zone's
countdown, after which a custom timer is set (AddTimerEx).
Signature
InstantZone_GetDuration( )Parameters
(none — the function is called without arguments)Usage example
if (myself.sm.flag != 2) {
InstantZone_GetDuration();
AddTimerEx(1002, 60 * 1000);
}InstantZone_AddExtraDurationNPC🟢 high
Extends the lifetime of the current instant zone by nExtraSec seconds. Used, for example,
to give the party extra time for killing a boss (+600 or +1200 s in the scripts).
Signature
InstantZone_AddExtraDuration( int nExtraSec )Parameters
nExtraSec (int) — extra lifetime for the instant zone, in seconds (1200 in the calls).Usage example
if ( InstantZone_ID >= 131 && InstantZone_ID <= 132 ) {
InstantZone_AddExtraDuration( 1200 );
}InstantZone_MarkRestrictionNPC🟢 high
Marks the player/party as having used the current instant zone — a re-entry restriction
that lasts until the instance resets. Called when the zone has the re-entry restriction
mode enabled.
Signature
InstantZone_MarkRestriction( )Parameters
(none — the function is called without arguments)Usage example
if ( InzoneRestriction == 1 ) {
InstantZone_MarkRestriction( );
}InstantZone_SendMakerEventNPC🟢 high
Broadcasts an event to the makers (spawners) of a specific instant zone. Per the L2NPC
decompile (CNPC::InstantZone_SendMakerEvent → CNpcMakerDB::InstantZoneEvent_53BB8C) the
engine finds the maker by zone type and cluster, then for every maker with a matching
event code calls NpcMakerEx::OnInstantZoneEvent. There are no direct calls in the scripts,
but the parameter semantics are visible in the code and the engine's error strings
("inzone type… clusterID… event…").
Signature
InstantZone_SendMakerEvent( int nInzoneType, int nClusterId, int nInzoneId, int nEvent, int nEventArg )Parameters
nInzoneType (int) — instant zone type (looked up in the maker DB; "inzone type" in the log).
nClusterId (int) — maker cluster id ("clusterID" in the log).
nInzoneId (int) — id of the specific instance copy the event is addressed to.
nEvent (int) — event code for the makers; special values: -1 = delete the zone maker,
-2 = create the zone maker; otherwise — the event code broadcast to matching makers.
nEventArg (int) — event data/argument, passed to the maker in OnInstantZoneEvent.
Example (illustrative):
InstantZone_SendMakerEvent( nInzoneType, nClusterId, nInzoneId, nEvent, nEventArg );InstantZone_GetTypeIdNPC🟢 high
Returns the type (type id) of the current instant zone — the numeric identifier of its
VARIETY from the instance data (which dungeon/hall it is by its template, not the individual
running instance). Takes no arguments — uses the instance this NPC is in. Returns 0 if the
NPC is not inside an instant zone. The result is usually compared against a named zone-type
constant to branch behaviour for a specific instance.
Zone types are named with @..._IZ_ID_* constants (values live in the manual_pch of the
relevant chronicle). In our chronicle, for example: @SSQ2_IZ_ID_AZIT_OF_DAWN=113,
@SSQ2_IZ_ID_TEMPLE_OF_SILENCE=151, @SSQ2_IZ_ID_LIB=156, @SSQ2_IZ_ID_HOME_OF_ELCADIA=158,
@MDE_IZ_ID=159, @MDE_IZ_ID_HELL=196, @SSQ25_IZ_ID_HOME_OF_ELCADIA=197. The set of ids
depends on the chronicle and its instance data.
NOTE: do not confuse the zone type (@..._IZ_ID_*) with the ENTRY type @eIZ_ET_* (ONLY_ME=0,
ALL_PARTY=1, COMMAND_CHANNEL=2) — the latter defines who is admitted on entry (an argument
of InstantZone_Enter) and has nothing to do with the value returned here.
Signature
InstantZone_GetTypeId( )Parameters
(none — the function is called without arguments)Returns
int — the type id of the instant-zone variety (see @..._IZ_ID_*), or 0 outside an instance.
Example (illustrative):
if ( InstantZone_GetTypeId( ) == @MDE_IZ_ID_HELL ) {
// behaviour branch for a specific instance
}GetInZoneIDMAKER🟢 high
Returns the identifier of the zone in which the maker was created. Called from the
maker's side (when an NPC is deleted), without arguments; plays the same zone-address role as
InstantZone_GetId.
Signature
GetInZoneID( )Parameters
(none — the function is called without arguments)Example
i0 = GetInZoneID( );
i2 = GetInZoneID( );DOORS, GATES AND AREAS (Doors / Gates / Areas)
8 functionsCastle_GateOpenClose2GLOBAL🟢 high
Opens or closes a named gate or door of a castle or fortress. The first
argument is the door name (a string from the script parameters, like a leaf name or a wall
section), the second is the state from the [manual_pch] dictionary: @CGOC_OPEN=0 means "open", and@CGOC_CLOSE=1 means "close". It is easy to err here: zero opens, one closes, not the
other way around. A global function on gg, returns an int.
Signature
Castle_GateOpenClose2( string sDoorName, int nOpenClose )Parameters
sDoorName (string) — the door/gate name from the world data.
nOpenClose (int) — the state [manual_pch]: @CGOC_OPEN=0 (open), @CGOC_CLOSE=1 (close).Example
Castle_GateOpenClose2( DoorName1, 0 );Castle_GateOpenCloseExGLOBAL🟢 high
An extended form of the previous function for doors inside an instance. The first two arguments are the
same — the door name and the state from the [manual_pch] dictionary (@CGOC_OPEN=0 open,@CGOC_CLOSE=1 close), and the third is the instant-zone identifier, to address the
door inside a specific instance. A global function on gg, returns an int.
Signature
Castle_GateOpenCloseEx( string sDoorName, int nOpenClose, int nInstZoneId )Parameters
sDoorName (string) — the name of the door being controlled
nOpenClose (int) — the state [manual_pch]: @CGOC_OPEN=0 (open), @CGOC_CLOSE=1 (close)
nInstZoneId (int) — the identifier of the instant zone in which the door is addressed (InstantZone_GetId())Example
Castle_GateOpenCloseEx(DoorName, @CGOC_OPEN, i2);Usage example
if ( arena == 4 ) {
Castle_GateOpenCloseEx( "olympiad_door_301", 0, InstantZone_GetId( ) );
Castle_GateOpenCloseEx( "olympiad_door_302", 0, InstantZone_GetId( ) );
}Area_SetOnOffGLOBAL🟢 high
Turns a named world area on or off. These are effect zones — territories that
give a buff or debuff, for example healing, empowerment, or harmful effects, as well as an entry ban.
The first argument is the zone name from the script parameters, the second is the state: one
turns it on, zero turns it off. A global function on gg, returns an int.
Signature
Area_SetOnOff( string sAreaName, int nOnOff )Parameters
sAreaName (string) — the name of the area zone (from the script parameters) that is turned on or off
nOnOff (int) — the zone state: 1 turns it on (@AS_ON), 0 turns it offExample
Area_SetOnOff( areadata_heal1, 0 );Area_SetOnOffExGLOBAL🟢 high
An extended form of controlling a named area. The first two arguments are the same — the zone name
and the state (one turns it on, zero turns it off), and the third is an additional parameter.
A global function on gg, returns an int.
Signature
Area_SetOnOffEx( string sAreaName, int nOnOff, int nInstZoneId )Parameters
sAreaName (string) — the name of the zone being controlled
nOnOff (int) — the zone state: 1 turns it on (@AS_ON), 0 turns it off
nInstZoneId (int) — the instant-zone identifier for addressing (InstantZone_GetId())Example
Area_SetOnOffEx(AREA_effect_1s_01, @AS_ON, i0);Usage example
if ( IsSameString( areadata, "extended_door_trap_area_default" ) == 0 ) {
Area_SetOnOffEx( areadata, 1, InstantZone_GetId( ) );
}Area_SetBannedTerritoryOnOffGLOBAL🟢 high
Controls a restricted territory — an area that entry into is blocked. A named area
contains a list of sub-territories; the function turns the ban on/off for a SPECIFIC sub-territory
by its index. Per the L2Server handler (NpcAreaSetBannedTerritoryOnOff → CArea::SetBannedTerritoryOnOff),
the third argument is the index of the sub-territory in the area's list: the server takes the territory with that number
and toggles its state; if the index exceeds the number of territories — it does nothing.
A global function on gg, returns an int.
Signature
Area_SetBannedTerritoryOnOff( string sTerritoryName, int nOnOff, int nTerritoryIndex, int nInstZoneId )Parameters
sTerritoryName (string) — the name of the area (a set of restricted territories) being controlled.
nOnOff (int) — the state: 1 turns the ban on, 0 removes it.
nTerritoryIndex (int) — the index of the sub-territory within the area (0-based; 0, 2, 3, 4 in calls;
the server toggles the territory with that number, out of bounds — a no-op).
nInstZoneId (int) — the instant-zone identifier (InstantZone_GetId()).Example
Area_SetBannedTerritoryOnOff(s0, i1, 0, InstantZone_GetId());InzoneDoorBreakableGLOBAL🟢 high
Makes a named instant-zone door breakable: the first argument is the door name,
the second is the instant-zone identifier where this door is located (InstantZone_GetId() in calls).
The door name is validated (an invalid one → an error in the log). Per decompile — a thin forwarder (opcode 188),
the function has no "breakable/not" flag. A global function on gg.
Signature
InzoneDoorBreakable( string sDoorName, int nInstZoneId )Parameters
sDoorName (string) — the name of the instance door being made breakable.
nInstZoneId (int) — the identifier of the instant zone where the door is located (InstantZone_GetId()).Example
InzoneDoorBreakable("gate_of_fortress", InstantZone_GetId());SetDoorHpLevelNPC🟢 high
Sets the "HP level" of a door in an instant zone: the first argument is the door name, the second —
the durability level. The engine substitutes the current instant-zone identifier itself. Sends
the server the corresponding command. Returns nothing.
Signature
SetDoorHpLevel( string sDoorName, int nHpLevel )Parameters
sDoorName (string) — the name of the instance door for which the durability is set.
nHpLevel (int) — the durability level ("HP level") of the door.Example
SetDoorHpLevel(WallName1, i1);GetDoorHpLevelNPC🟢 high
Requests the "HP level" of a door in an instant zone. This is an ASYNCHRONOUS request (like
IsToggleSkillOnOff): the function itself returns nothing — the engine sends the server a request,
and the result arrives as a separate event; the first argument (the addressee) — whom the answer is
intended for, the second — the door name. The engine substitutes the instant-zone identifier itself.
Signature
GetDoorHpLevel( CSharedCreatureData c, string sDoorName )Parameters
c (CSharedCreatureData) — the addressee of the request, to whom the result is returned (via an event).
sDoorName (string) — the name of the instance door whose durability is requested.Example
GetDoorHpLevel(talker, WallName1);TERRITORY FIELD CYCLE (FieldCycle)
7 functionsGetStep_FieldCycleGLOBAL🟢 high
Returns the current phase (Step) of a cycle. Takes the cycle identifier nFieldId (a class parameter),
called on the global object gg. Returns the discrete stage number, which is usually
compared with a number to decide what to do next.
Signature
GetStep_FieldCycle( int nFieldId )Parameters
nFieldId (int) — the identifier of the cycle (a class parameter) whose current phase is requested.Example
i1 = GetStep_FieldCycle(3);Usage example
i0 = GetStep_FieldCycle( FieldCycle2 );
if ( i0 >= Threshold_Level_Min2 && i0 <= Threshold_Level_Max2 ) {
}GetPoint_FieldCycleGLOBAL🟢 high
Returns the current progress (Point) of a cycle — a counter within the phase. Takes the cycle identifier
nFieldId, called on the global object gg. Returns the accumulated number of points, which is
compared with the transition threshold.
Signature
GetPoint_FieldCycle( int nFieldId )Parameters
nFieldId (int) — the identifier of the cycle whose progress is requestedExample
i1 = GetPoint_FieldCycle(FieldCycle);Usage example
i1 = GetPoint_FieldCycle( FieldCycle );
if ( i0 < Threshold_Min || i0 > Threshold_Max || i1 < Point_Min || i1 > Point_Max ) {
created_npc.Despawn( );
}AddPoint_FieldCycleGLOBAL🟢 high
Adds nPoint progress points to the cycle nFieldId; nReason is the reason code (a raw number, most often
one for a kill by a player), c is who the credit is for (the last attacker or the managermyself.sm itself). Called on the global object gg. On reaching the threshold, usually a
phase switch follows.
Signature
AddPoint_FieldCycle( int nFieldId, int nPoint, int nReason, CSharedCreatureData cCreature )Parameters
nFieldId (int) — the identifier of the cycle to which progress points are credited
nPoint (int) — the number of progress points credited
nReason (int) — the credit reason code (a raw number, most often 1 for a kill by a player)
cCreature (CSharedCreatureData) — the creature the points are credited for (the last attacker or the manager itself)Example
AddPoint_FieldCycle(1, 5 * 20, 4, talker);Usage example
if (i0 == 1) {
AddPoint_FieldCycle(FieldCycle_ID, FieldCycle_point, 1, myself.sm);
}SetStep_FieldCycleGLOBAL🟢 high
Moves the cycle nFieldId into a new phase nStep and broadcasts an event to all subscribed NPCs and
makers — this is exactly how they learn it is time to change behavior. Takes the reason code nReason
(a raw number) and the initiator creature c, called on the global object gg.
Signature
SetStep_FieldCycle( int nFieldId, int nStep, int nReason, CSharedCreatureData cCreature )Parameters
nFieldId (int) — the identifier of the cycle moved into a new phase
nStep (int) — the number of the cycle's new phase
nReason (int) — the reason code for the phase change (a raw number)
cCreature (CSharedCreatureData) — the creature initiating the phase changeExample
SetStep_FieldCycle( FieldCycle, 5, 1, c0 );Usage example
if ( i0 == 0 ) {
SetStep_FieldCycle( RaceCycleID, 1, 8, myself.sm );
}
Related event: the phase change broadcasts ON_FIELD_CYCLE_CHANGED_EVENT(event_id, state, i1) to subscribers; the phase timer expiration arrives as FIELD_CYCLE_STEP_EXPIRED. Subscription — RegisterFieldCycleEventEx / RegisterAsFieldCycleManager (see NASC_HANDLERS).SetStepWithoutActor_FieldCycleGLOBAL🟢 high
The paired form of switching phase for the case when the initiator creature is unknown and is not
passed. Takes the cycle identifier nFieldId, the new phase nStep, and the reason code nReason,
called on the global object gg. A typical pairing: if there is a player — the ordinary form is called,
otherwise the form without an actor.
Signature
SetStepWithoutActor_FieldCycle( int nFieldId, int nStep, int nReason )Parameters
nFieldId (int) — the identifier of the cycle whose phase is switched
nStep (int) — the new phase of the cycle
nReason (int) — the reason code for the switchExample
SetStepWithoutActor_FieldCycle( 1, 9, 5 );
SetStepWithoutActor_FieldCycle( FieldCycle, 5, 1 );
SetStepWithoutActor_FieldCycle(FieldCycle, 1, 1);
SetStepWithoutActor_FieldCycle(FieldCycle, 8, 5);
Related event: like SetStep_FieldCycle, the phase change broadcasts ON_FIELD_CYCLE_CHANGED_EVENT to subscribers; the phase timer expiration — FIELD_CYCLE_STEP_EXPIRED (see NASC_HANDLERS).RegisterAsFieldCycleManagerNPC🟢 high
Marks the NPC as a cycle manager, giving it the right to change the phase and progress. No
arguments, called on the NPC (myself), usually in the creation handler. The phase-change
events themselves are "phase changed" and "phase timer expired"; they arrive to subscribers
and are described in the events file.
Signature
RegisterAsFieldCycleManager( )Parameters
(none — the function is called without arguments)Example
RegisterAsFieldCycleManager();
Related event: the manager receives cycle events — ON_FIELD_CYCLE_CHANGED_EVENT (phase change) and FIELD_CYCLE_STEP_EXPIRED (phase timer expired). Targeted subscription to a specific cycle — RegisterFieldCycleEventEx (see NASC_HANDLERS).RegisterFieldCycleEventExMAKER🟢 high
Subscribes the maker to events of cycle nFieldId: after the call it receives notifications about
phase changes. Called on the maker (myself), usually at startup. The return value is auxiliary;
the point of the call is establishing the subscription.
Signature
RegisterFieldCycleEventEx( int nFieldId )Parameters
nFieldId (int) — identifier of the cycle whose events the maker is subscribed to.Example
RegisterFieldCycleEventEx( 1 );
RegisterFieldCycleEventEx( FieldCycle );
RegisterFieldCycleEventEx( FieldCycle_ID );Usage example
if ( FieldCycle != -1 ) {
RegisterFieldCycleEventEx( FieldCycle );
}
Related event: after subscribing, the maker receives cycle events — ON_FIELD_CYCLE_CHANGED_EVENT (phase change) and FIELD_CYCLE_STEP_EXPIRED (phase timer expired). The phase is changed by SetStep_FieldCycle / SetStepWithoutActor_FieldCycle (see NASC_HANDLERS).SPEECH AND ANNOUNCEMENTS (Say / Chat)
11 functionsAnnounceGLOBAL🟢 high
A global announcement from the global object gg, not from a specific NPC,
in literal text. Takes one argument sMessage (string) without namespace. Returns nothing
(void).
Signature
Announce( string pStr1 )Parameters
pStr1 (string) — the text of the global announcementExample
Announce("DV");Usage example
if ( is_debug ) {
Announce( "Follower_frintessa: Summoning final form. Start sequence" );
}AnnounceFStrGLOBAL🟢 high
A global announcement from the global object gg using a localized NPC-string with
parameters. Takes nNpcStringId (int) — the string id — and up to five substitutions p1..p5
(string), without namespace. Returns nothing (void).
Signature
AnnounceFStr( int nArg1, string pStr1, string pStr2, string pStr3, string pStr4, string pStr5 )Parameters
nArg1 (int) — the identifier of the localized NPC-string for the global announcement
pStr1 (string) — the first string substitution into the NPC-string (unused ones passed as `_blank`)
pStr2 (string) — the second string substitution into the NPC-string (unused ones passed as `_blank`)
pStr3 (string) — the third string substitution into the NPC-string (unused ones passed as `_blank`)
pStr4 (string) — the fourth string substitution into the NPC-string (unused ones passed as `_blank`)
pStr5 (string) — the fifth string substitution into the NPC-string (unused ones passed as `_blank`)Example
AnnounceFStr(1100030, "", "", "", "", "");Usage example
if ( IsNullCreature( last_attacker ) == @FALSE ) {
AnnounceFStr( 3603428, "Antharas", last_attacker.name, _blank, _blank, _blank );
}SayNPC🟢 high
The NPC utters a line (pop-up text above its head), visible locally to players
nearby. Takes a single argument sText (string) without a namespace; most often
MakeFString(...) with an NPC-string id is passed in, literal strings appear in debug
messages. Returns int.
Signature
Say( string sText )Parameters
sText (string) — text (often MakeFString(npcStringId, ...)).Example
Say( "Amendment. There is not a master" );Usage example
if ( c0.is_pc == 1 ) {
Say( MakeFString( 9858, c0.name, _blank, _blank, _blank, _blank ) );
}SayFStrNPC🟢 high
Same as Say(MakeFString(id, p1..p5)), but in a single call: utters the localized
NPC-string nNpcStringId (int), substituting up to five string parameters p1..p5
(string), no namespace; unused ones are passed as _blank/"". The string text for
this id resides in the chronicle's fstring.txt. Returns int.
Signature
SayFStr( int nArg1, string pStr1, string pStr2, string pStr3, string pStr4, string pStr5 )Parameters
nArg1 (int) — id of the localized client string.
pStr1 (string) — first string substitution into the localized NPC-string (pass `_blank` when unused)
pStr2 (string) — second string substitution into the localized NPC-string (pass `_blank` when unused)
pStr3 (string) — third string substitution into the localized NPC-string (pass `_blank` when unused)
pStr4 (string) — fourth string substitution into the localized NPC-string (pass `_blank` when unused)
pStr5 (string) — fifth string substitution into the localized NPC-string (pass `_blank` when unused)Example
SayFStr(18455, "", "", "", "", "");Usage example
if ( c0.is_pc == @TRUE ) {
SayFStr( 9858, c0.name, _blank, _blank, _blank, _blank );
}SayIntNPC🟢 high
Utters a numeric value as an NPC line — a debug way to print a number, the Say
analog for numbers. Takes a single argument nValue (int64) without a namespace. Returns int.
Signature
SayInt( int64 nValue )Parameters
nValue (int64) — number to print.Example
SayInt(1);SayFloatNPC🟢 high
Like SayInt, but for a floating-point number: debug output of a float as an NPC line. Takes
a single argument fValue (float) without a namespace. Returns nothing (void).
Signature
SayFloat( float fValue )Parameters
fValue (float) — floating-point number to print.
Example (illustrative):
SayFloat( 0.0 );ShoutNPC🟢 high
Like Say, but with a larger radius — a "shout" heard across the district (shout channel), not
just up close; this is how bosses announce combat phases and events. Takes a single argument
sText (string) without a namespace, often MakeFString(...). Returns int.
Signature
Shout( string sText )Parameters
sText (string) — text (often MakeFString(...)).Example
Shout( "I'm coming..." );Usage example
if ( ShoutMsg1 > 0 ) {
Shout( MakeFString( ShoutMsg1, _blank, _blank, _blank, _blank, _blank ) );
}ShoutFStrNPC🟢 high
A "shout" via NPC-string — Shout and MakeFString combined in one call, with shout radius.
Takes nNpcStringId (int) — the id of the localized string (the text for this id resides
in the chronicle's fstring.txt) — and up to five substitutions p1..p5 (string), no namespace.
Returns int.
Signature
ShoutFStr( int nNpcStringId, string pStr1, string pStr2, string pStr3, string pStr4, string pStr5 )Parameters
nNpcStringId (int) — id of the localized string.
pStr1 (string) — first string substitution into the localized shout NPC-string (pass `_blank` when unused)
pStr2 (string) — second string substitution into the localized shout NPC-string (pass `_blank` when unused)
pStr3 (string) — third string substitution into the localized shout NPC-string (pass `_blank` when unused)
pStr4 (string) — fourth string substitution into the localized shout NPC-string (pass `_blank` when unused)
pStr5 (string) — fifth string substitution into the localized shout NPC-string (pass `_blank` when unused)Example
ShoutFStr( 99601, "", "", "", "", "" );Usage example
if ( msg_dying > 0 ) {
ShoutFStr( msg_dying, _blank, _blank, _blank, _blank, _blank );
}ShoutExNPC🟢 high
An extended shout variant with an explicit audibility radius. The text and radius are sent to the game
server via an opcode 100 packet; the handler (L2Server: NpcShout → CNPC::Shout_720900) uses
the second argument as the broadcast radius of the shout to nearby players (BroadcastToNeighborRect). The engine
caps the radius at 16384: if 0 or more than 16384 is passed, 16384 is used.
In the call = 1500. Returns nothing.
Signature
ShoutEx( string sText, int nRange )Parameters
sText (string) — the NPC's shout text (often MakeFString(...)).
nRange (int) — audibility radius of the shout in world units (0 or >16384 → engine uses 16384; 1500 in the call).Example
ShoutEx(MakeFString(1000380, "", "", "", "", ""), 1500);Usage example
if ( ShoutMsg == 1 ) {
ShoutEx( MakeFString( 1000457, _blank, _blank, _blank, _blank, _blank ), 11500 );
}ShoutFStrExNPC🟢 high
Same as ShoutEx (a "shout" in a bubble above the NPC that surrounding players see), except the text
is taken not as a ready-made string but by the id of a localized NPC-string, into which up to
five string pieces are substituted immediately. The first argument is the phrase id, followed by five
substitution slots (placeholders in the phrase template; unused slots are filled with _blank), and the last
argument is the audibility radius in game world units: the larger it is, the farther from the NPC
players will see the shout. The calls use 11500 (a shout over a large area around the arena) or 3000
(a close-range shout at a waypoint). The engine trims an overly large radius to the 16384 limit.
Returns nothing. Convenient when the phrase already resides in the localization table and you don't
want to assemble it manually via MakeFString.
Signature
ShoutFStrEx( int nNpcStringId, string pStr1, string pStr2, string pStr3, string pStr4, string pStr5, int nRectOffset )Parameters
nNpcStringId (int) — id of the localized NPC-string the NPC will shout
pStr1 (string) — 1st substitution into the phrase template (pass `_blank` when unused)
pStr2 (string) — 2nd substitution (pass `_blank` when unused)
pStr3 (string) — 3rd substitution (pass `_blank` when unused)
pStr4 (string) — 4th substitution (pass `_blank` when unused)
pStr5 (string) — 5th substitution (pass `_blank` when unused)
nRectOffset (int) — audibility radius of the shout in world units: how far around the NPC
players will see the phrase (11500 and 3000 in the calls; an overly large value is capped by the engine at 16384)Example
ShoutFStrEx(1000457, _blank, _blank, _blank, _blank, _blank, 11500);Usage example
if ( myself.i_ai1 >= myself.i_ai2 ) { // reached the end of the route
ShoutFStrEx( 12000008, _blank, _blank, _blank, _blank, _blank, 3000 );
RemoveAllDesire( );
Despawn( );
return;
}GlobalAnnounceNPC🟢 high
Makes an announcement on behalf of the NPC with a specified channel type and text — for important
notifications (events, sieges). Takes nAnnounceType (int) — the announcement type/channel
(table unconfirmed) — and sMessage (string), no namespace. Returns nothing
(void).
Signature
GlobalAnnounce( int nAnnounceType, string sAnnounceMessage )Parameters
nAnnounceType (int) — announcement type/channel (table unconfirmed).
sAnnounceMessage (string) — announcement text.
Example (illustrative):
GlobalAnnounce( nAnnounceType, "" );Dialogs, menus, messages (Dialogs / Messages)
12 functionsShowOnScreenMsgStrGLOBAL🟢 high
Displays to the creature c large cutscene text at the center of the screen (not in chat), akin to BroadcastOnScreenMsg*, but addressed to a single c. The numeric arguments between c and the string set the position, effect type, display time, and fade; sText is the string itself.
Signature
ShowOnScreenMsgStr( CSharedCreatureData cCreature, int nMsgPosType, int nParam1, int nFontSize, int nParam2, int nParam3, int nEffect, int nTime, int nFade, string sMsg )
Parameters (the same ExShowScreenMessage packet fields as in BroadcastOnScreenMsgStr, but without a radius —
addressed to a single creature; confirmed by the engine source, message type = 1 "arbitrary text"):
cCreature (CSharedCreatureData) — the creature shown the on-screen text.
nMsgPosType (int) — the message position on the screen. 2 in calls.
nParam1 (int) — a service packet field (unnamed in the engine). 0 in calls.
nFontSize (int) — font size. 0 in calls.
nParam2 (int) — a service packet field (unnamed in the engine). 0 in calls.
nParam3 (int) — a service packet field (unnamed in the engine). 0/1 in calls.
nEffect (int) — the text's visual appearance effect. 0/1 in calls.
nTime (int) — display duration, ms. 1000/3000/10000 in calls.
nFade (int) — fade effect. 0 in calls.
sMsg (string) — the text string to display.Example
ShowOnScreenMsgStr( c3, 2, 0, 0, 0, 1, 0, 10000, 0, s0 );
ShowOnScreenMsgStr( myself.c_ai1, 2, 0, 0, 0, 1, 0, 1000, 0, " " );
ShowOnScreenMsgStr( attacker, 2, 0, 0, 0, 1, 0, 3000, 0, s0 );
ShowOnScreenMsgStr( talker, 2, 0, 0, 0, 1, 0, 3000, 0, "Exposure" );Usage example
if ( IsNullCreature( c3 ) == 0 ) {
ShowOnScreenMsgStr( c3, 2, 0, 0, 0, 1, 0, 10000, 0, s0 );
}ShowOnScreenMsgFStrGLOBAL🟢 high
The same as ShowOnScreenMsgStr, but the text is given by a phrase id with substitutions (p1..p5). The numeric arguments set the position, effect type, display time, and fade.
Signature
ShowOnScreenMsgFStr( CSharedCreatureData cCreature, int nMsgPosType, int nParam1, int nFontSize, int nParam2, int nParam3, int nEffect, int nTime, int nFade, int nNpcStringId, string p1, string p2, string p3, string p4, string p5 )
Parameters (same fields as ShowOnScreenMsgStr, but the text is not a string — it is an
npcString phrase id with p1..p5 substitutions):
cCreature (CSharedCreatureData) — the creature shown the on-screen text.
nMsgPosType (int) — message position on screen. In calls 2/5.
nParam1 (int) — service packet field (unnamed in the engine). In calls 0.
nFontSize (int) — font size. In calls 0.
nParam2 (int) — service packet field. In calls 0.
nParam3 (int) — service packet field. In calls 0/1.
nEffect (int) — text appearance effect. In calls 0/1.
nTime (int) — display duration, ms. In calls 4000/5000.
nFade (int) — fade-out effect. In calls 0.
nNpcStringId (int) — phrase id (npcString) into which p1..p5 are substituted. In calls 36810804.
p1..p5 (string) — phrase substitutions in order; unused ones pass _blank / "".Example
ShowOnScreenMsgFStr(target, 5, 0, 0, 0, 1, 0, 5000, 0, 36810804, _blank, _blank, _blank, _blank, _blank);Usage example
if ( myself.sm.param2 == 0 ) {
ShowOnScreenMsgFStr( myself.c_ai0, 2, 0, 0, 0, 0, 1, 4000, 0, 1801149, "", "", "", "", "" );
}AddChoiceNPC🟢 high
Adds one entry to the NPC dialog choice menu: nCode — the code returned when the entry is chosen, pwsMsg — the entry text (usually MakeFString(fstringId, ...)). After collecting the entries, the menu is shown via ShowChoicePage.
Signature
AddChoice( int nCode, string pwsMsg )Parameters
nCode (int) — code returned when this menu entry is chosen
pwsMsg (string) — menu entry textExample
AddChoice( 0, MakeFString( 15501, _blank, _blank, _blank, _blank, _blank ) );AddChoiceExNPC🟢 high
Same as AddChoice, plus a third argument nColor — the entry text color. nCode — entry code, the second argument — the text (a string, usually MakeFString).
Signature
AddChoiceEx( int nCode, string pwsMsg, int nColor )Parameters
nCode (int) — code returned when this menu entry is chosen
pwsMsg (string) — menu entry text
nColor (int) — entry text colorExample
AddChoiceEx( 0, MakeFString( 23402, _blank, _blank, _blank, _blank, _blank ), @qcc_progress );AddChoiceFStrExNPC🟢 high
Adds a menu entry whose text is given directly by phrase id nFstringId (without the MakeFString wrapper): nCode — entry code, nColor — color.
Signature
AddChoiceFStrEx( int nCode, int nFstringId, int nColor )Parameters
nCode (int) — code returned when this menu entry is chosen
nFstringId (int) — id of the phrase providing the entry text
nColor (int) — entry text colorExample
AddChoiceFStrEx(0, 17001551, @QCCE_START);ShowChoicePageNPC🟢 high
Displays to player cCreature the choice menu previously assembled (via AddChoice*). The second argument nOption is the menu mode/page number.
Signature
ShowChoicePage( CSharedCreatureData cCreature, int nOpton )Parameters
cCreature (CSharedCreatureData) — player to whom the choice menu is shown
nOpton (int) — menu mode/page numberExample
ShowChoicePage( talker, 1 );
ShowChoicePage( talker, 0 );
ShowChoicePage(talker,0);Usage example
if ( _choiceN > 1 ) {
ShowChoicePage( talker, 1 );
return;
}ShowSystemMessageNPC🟢 high
Shows creature c a system message (the yellow system chat line). nSysMsgNo — the message number from the client system message table.
Signature
ShowSystemMessage( CSharedCreatureData cCreature, int nSysMsgNo )Parameters
cCreature (CSharedCreatureData) — creature shown the system message
nSysMsgNo (int) — system message number from the client tableExample
if (GetInventoryInfo(talker, @IPT_CURRENT_QUEST_SCOUNT) >= (GetInventoryInfo(talker, @IPT_MAX_QUEST_SCOUNT) * 0.9) || GetInventoryInfo(talker, @IPT_CURRENT_WEIGHT) >= (GetInventoryInfo(talker, @IPT_MAX_CARRY_WEIGHT) * 0.9) || GetInventoryInfo(talker, @IPT_CURRENT_SLOT_COUNT) >= (GetInventoryInfo(talker, @IPT_MAX_SLOT_COUNT) * 0.9)) { ShowSystemMessage(talker, 3262); return; }Usage example
if ( GetInventoryInfo( talker, @IPT_CURRENT_SLOT_COUNT ) >= ( GetInventoryInfo( talker, @IPT_MAX_SLOT_COUNT ) * 0.800000 ) || GetInventoryInfo( talker, @IPT_CURRENT_WEIGHT ) >= ( GetInventoryInfo( talker, @IPT_MAX_CARRY_WEIGHT ) * 0.800000 ) ) {
ShowSystemMessage( talker, 1118 );
return;
}ShowSystemMessage2NPC🟢 high
Shows creature c system message nSysMsgNo, substituting parameters into its template: nParamCount — the number of substitutions, followed by up to eight string values (p1..p8).
Signature
ShowSystemMessage2( CSharedCreatureData cCreature, int nSysMsgNo, int nParamCount, string pwsParam1, string pwsParam2, string pwsParam3, string pwsParam4, string pwsParam5, string pwsParam6, string pwsParam7, string pwsParam8 )Parameters
cCreature (CSharedCreatureData) — creature shown the system message
nSysMsgNo (int) — system message number from the client table
nParamCount (int) — number of substituted parameters
pwsParam1 (string) — substitution 1 into the message template
pwsParam2 (string) — substitution 2 into the message template
pwsParam3 (string) — substitution 3 into the message template
pwsParam4 (string) — substitution 4 into the message template
pwsParam5 (string) — substitution 5 into the message template
pwsParam6 (string) — substitution 6 into the message template
pwsParam7 (string) — substitution 7 into the message template
pwsParam8 (string) — substitution 8 into the message templateExample
ShowSystemMessage2(talker, 8373, 1, _blank, _blank, _blank, _blank, _blank, _blank, _blank, _blank);ShowSystemMessageStrNPC🟢 high
Displays to creature c an already prepared string sText as a system message (without a template from the client table).
Signature
ShowSystemMessageStr( CSharedCreatureData cCreature, string sText )Parameters
cCreature (CSharedCreatureData) — creature shown the system message
sText (string) — ready-made message text stringExample
ShowSystemMessageStr( talker, s0 );Usage example
if (creature.is_pc) {
ShowSystemMessageStr(creature, MakeFString(1800294, myself.c_ai2.name, "", "", "", ""));
}ShowSystemMessageFStrNPC🟢 high
Shows creature c system message nSysMsgNo, substituting up to five string values (p1..p5) into the phrase template.
Signature
ShowSystemMessageFStr( CSharedCreatureData cCreature, int nArg0, string pStr1, string pStr2, string pStr3, string pStr4, string pStr5 )Parameters
cCreature (CSharedCreatureData) — creature shown the system message
nArg0 (int) — system message number from the client table
pStr1 (string) — substitution 1 into the message template
pStr2 (string) — substitution 2 into the message template
pStr3 (string) — substitution 3 into the message template
pStr4 (string) — substitution 4 into the message template
pStr5 (string) — substitution 5 into the message templateExample
ShowSystemMessageFStr(talker, 1800250, _blank, _blank, _blank, _blank, _blank);WhisperNPC🟢 high
The NPC whispers a private string sStr only to the addressee pTalker (unlike Say/Shout, which those nearby can hear).
Signature
Whisper( CSharedCreatureData pTalker, string sStr )Parameters
pTalker (CSharedCreatureData) — addressee to whom the NPC whispers privately
sStr (string) — the whispered text stringExample
Whisper(creature, "status " + s0);WhisperFStrNPC🟢 high
Same as Whisper, but the text is given by an NPC-string id (nNpcStringId) with substitutions (p1..p5); the addressee is c.
Signature
WhisperFStr( CSharedCreatureData cCreature, int nNpcStringId, string pStr1, string pStr2, string pStr3, string pStr4, string pStr5 )Parameters
cCreature (CSharedCreatureData) — addressee to whom the NPC whispers privately
nNpcStringId (int) — NPC-string id providing the whisper text
pStr1 (string) — substitution 1 into the text template
pStr2 (string) — substitution 2 into the text template
pStr3 (string) — substitution 3 into the text template
pStr4 (string) — substitution 4 into the text template
pStr5 (string) — substitution 5 into the text templateExample
WhisperFStr( c0, 60018, _blank, _blank, _blank, _blank, _blank );Usage example
if ( myself.i_ai1 == 2 ) {
WhisperFStr( c0, 60020, _blank, _blank, _blank, _blank, _blank );
SendScriptEvent( myself.sm, 45702, 0 );
}DIALOG HTML WINDOWS (FHTML)
7 functionsShowPageNPC🟢 high
Shows the player a ready HTML page by the .htm file name without any
substitutions. Takes whom to show (usually talker) and the html file name; returns
nothing. The most frequent way to give an NPC's line or menu; the file name is often stored
in a variable.
Related event: the selection of an html-menu item arrives as the MENU_SELECTED(talker, ask, reply) event (see NASC_HANDLERS).
Signature
ShowPage( CSharedCreatureData cCreature, string pwsPage )Parameters
cCreature (CSharedCreatureData) — whom to show (usually talker).
pwsPage (string) — the html file name.Example
ShowPage( talker, fnHi );Usage example
if ( talker.level >= 46 && talker.level < 52 ) {
ShowPage( talker, "reflect_weapon_c.htm" );
}FHTML_SetFileNameNPC🟢 high
Sets the window buffer's html template, into which values will then be substituted. This is the
first step of building a dynamic window. Takes the window buffer (usually fhtml0) and the
html template name; returns nothing.
Signature
FHTML_SetFileName( CFHTML fhtml, string sFileName )Parameters
fhtml (CFHTML) — the window buffer (usually fhtml0).
sFileName (string) — the html template name.Example
FHTML_SetFileName(fhtml0, s0 );Usage example
if ( ask == -201 ) {
FHTML_SetFileName( fhtml0, "map_agit_" + fnAgitMap + ".htm" );
ShowFHTML( talker, fhtml0 );
}FHTML_SetStrNPC🟢 high
Substitutes a string value into the template in place of the placeholder with the given key.
Takes the window buffer, the placeholder name, and the substituted string; returns nothing.
Passing _blank clears the field — this is often used to hide a button or block.
Signature
FHTML_SetStr( CFHTML fhtml, string sKey, string sValue )Parameters
fhtml (CFHTML) — the window buffer.
sKey (string) — the placeholder name.
sValue (string) — the substituted string.Example
FHTML_SetStr( fhtml0, "HP" + "Reset", _blank );Usage example
if ( IsNull( pledge0 ) == 0 ) {
FHTML_SetStr( fhtml0, "pledge0", pledge0.name );
FHTML_SetStr( fhtml0, "p_member_count0", IntToStr( i1 ) );
}FHTML_SetIntNPC🟢 high
Substitutes an integer value in place of the placeholder with the given key. Takes
the window buffer, the placeholder name, and the number; returns nothing. Used to display
prices, quantities, percentages, and tax rates.
Signature
FHTML_SetInt( CFHTML fhtml, string sKey, int64 nValue )Parameters
fhtml (CFHTML) — the window buffer.
sKey (string) — the placeholder name.
nValue (int64) — the substituted integer value for the placeholderExample
FHTML_SetInt( fhtml0, "quest_id", @black_swan );Usage example
if ( Agit_GetDecoLevel( decotype_hpregen ) == 0 ) {
FHTML_SetInt( fhtml0, "HPDepth", 0 );
} else {
FHTML_SetInt( fhtml0, "HPDepth", ( Agit_GetDecoLevel( decotype_hpregen ) * 20 ) );
}FHTML_SetFloatNPC🟢 high
Substitutes a fractional value in place of the placeholder with the given key. Takes the window
buffer, the placeholder name, and the number; returns nothing. Applied in the same places as the
integer variant — for values with a fractional part.
Signature
FHTML_SetFloat( CFHTML fhtml, string sKey, float fValue )Parameters
fhtml (CFHTML) — the dialog window buffer (`fhtml0`) into which the substitution goes
sKey (string) — the placeholder name in place of which the value is substituted
fValue (float) — the substituted fractional value for the placeholder
Example (illustrative):
FHTML_SetFloat( fhtml0, "", 0.0 );FHTML_SetFStrNPC🟢 high
Substitutes in place of the placeholder a localized NPC-string by its identifier with
five string parameters — the same as building a string from an identifier and inserting
it, but in one call. Takes the window buffer, the placeholder name, the localized string id,
and five substitutions; returns nothing. For localized captions and buttons in the window.
Signature
FHTML_SetFStr( CFHTML pfhtml, string pStr1, int nArg1, string pStr2, string pStr3, string pStr4, string pStr5, string pStr6 )Parameters
pfhtml (CFHTML) — the window buffer.
pStr1 (string) — the placeholder name.
nArg1 (int) — the localized string id.
pStr2 (string) — the first string substitution into the localized string
pStr3 (string) — the second string substitution into the localized string
pStr4 (string) — the third string substitution into the localized string
pStr5 (string) — the fourth string substitution into the localized string
pStr6 (string) — the fifth string substitution into the localized stringExample
FHTML_SetFStr( fhtml0, "QuizString", 1010635, "", "", "", "", "" );Usage example
if (GetAbnormalLevel(talker, Skill_GetAbnormalType(buff1)) >= Skill_GetAbnormalLevel(buff1)) { FHTML_SetStr(fhtml0, "bypass_buff1", _blank); FHTML_SetFStr(fhtml0, "button_type1", 36810606, _blank, _blank, _blank, _blank, _blank); }
else { FHTML_SetStr(fhtml0, "bypass_buff1", "bypass -h menu_select?ask=-301&reply=1"); FHTML_SetFStr(fhtml0, "button_type1", 36810605, _blank, _blank, _blank, _blank, _blank); }ShowFHTMLNPC🟢 high
Shows the player the assembled window from the buffer — the final step of a dynamic window after
setting the template and a series of substitutions. Takes whom to show and the filled window buffer;
returns nothing.
Signature
ShowFHTML( CSharedCreatureData cCreature, CFHTML fhtml )Parameters
cCreature (CSharedCreatureData) — whom to show.
fhtml (CFHTML) — the filled window buffer.Example
ShowFHTML( talker, fhtml0 );Usage example
if ( i8 != 4 ) {
ShowFHTML( talker, fhtml0 );
} else {
ShowPage( talker, "master_lv3_hef_07.htm" );
}EVENTS AND BROADCASTS (Events / Broadcast)
13 functionsSendScriptEventGLOBAL🟢 high
Sends a script event to a specific creature/NPC c by address, not
broadcast. Takes CSharedCreatureData c, int nEventId, and int nParam (without
namespace), returns an int (apparently, a delivery/handling flag). Used for
"master → its minions" communication.
Related event: the addressee catches SCRIPT_EVENT; SendMakerScriptEvent → maker ON_SCRIPT_EVENT (see NASC_HANDLERS).
Signature
SendScriptEvent( CSharedCreatureData cCreature, int nEventId, int nParam )Parameters
cCreature (CSharedCreatureData) — the event addressee (in calls c0/c1/c4).
nEventId (int) — the event code: a @SCE_* constant or an arbitrary number set by the script
(not a fixed enum; the addressee catches it in the SCRIPT_EVENT handler).
nParam (int) — data (often a creature index from GetIndexFromCreature).Example
SendScriptEvent( c1, @SCE_MPCC_ID, i0 );Usage example
if ( myself.i_ai1 > 135 ) {
SendScriptEvent( myself.c_ai2, 0, 0 );
}SendScriptEventExGLOBAL🟢 high
An addressed version of the event with two data fields for a specific creature. Takes
CSharedCreatureData c, int nEventId, int nParam2, and int nParam3 (without namespace),
returns an int.
Related event: the addressee catches SCRIPT_EVENT; SendMakerScriptEvent → maker ON_SCRIPT_EVENT (see NASC_HANDLERS).
Signature
SendScriptEventEx( CSharedCreatureData cCreature, int nEventId, int nParam2, int nParam3 )Parameters
cCreature (CSharedCreatureData) — the receiving creature of the event
nEventId (int) — the event code: @SCE_* or an arbitrary number (not a fixed enum)
nParam2 (int) — the first payload field of the event
nParam3 (int) — the second payload field of the eventExample
SendScriptEventEx(c0, @AI_MONSTER_ELITE_START, GetIndexFromCreature(myself.sm), 0);SendMakerScriptEventGLOBAL🟢 high
Sends an event with two data fields to a spawner (CNpcMakerEx), to control
spawn waves — for example, to start the next wave. Takes CNpcMakerEx maker,
int nEventId, int nParam2, and int nParam3 (without namespace), returns an int. For
territory wars there exists a related variety SendDominiSCRIPT_EVENT.
Signature
SendMakerScriptEvent( CNpcMakerEx maker, int nEventId, int nParam2, int nParam3 )Parameters
maker (CNpcMakerEx) — the receiving spawner of the event, controlling spawn waves
nEventId (int) — the event code: @SCE_* or an arbitrary number (not a fixed enum)
nParam2 (int) — the first payload field of the event
nParam3 (int) — the second payload field of the eventExample
SendMakerScriptEvent( maker0, 0, 0, 0 );Usage example
if ( IsNull( maker0 ) == 0 ) {
SendMakerScriptEvent( maker0, 1001, 0, 0 );
}BroadcastOnScreenMsgFStrGLOBAL🟢 high
Displays large text right on the screen (not in chat, but over the picture) to all players
around the source. The text is taken by the number of a ready (localized) phrase nNpcStringId,
its substitution slots are filled with the strings sStr1..sStr5. Where exactly the caption appears
(nMsgPosType), how long it stays (nTime, ms), and with what appearance/fade effect —
is set by numeric parameters. Used for dramatic notifications: a boss's
appearance, an event phase change. Returns nothing.
Signature
BroadcastOnScreenMsgFStr( CSharedCreatureData c, int nRange, int nMsgPosType, int nParam1, int nFontSize, int nParam2, int nParam3, int nEffect, int nTime, int nFade, int nNpcStringId, string sStr1, string sStr2, string sStr3, string sStr4, string sStr5 )Parameters
c (CSharedCreatureData) — the source creature; the circle whose players see the caption is measured around it
nRange (int) — visibility radius in game units: how far from the source the text is still shown (maximum 16384; 0 — minimal coverage right at the source)
nMsgPosType (int) — where on the screen to place the caption (a code designation of the screen zone; 1 and 2 in calls)
nParam1 (int) — a service output field (0 in calls)
nFontSize (int) — font size (0 — default size)
nParam2 (int) — a service output field (0 in calls)
nParam3 (int) — a service output field (0 in calls)
nEffect (int) — the caption's appearance effect (0 — no effect, 1 — with effect)
nTime (int) — how long to keep the caption on screen, milliseconds (3000 and 10000 in calls)
nFade (int) — smooth fade on disappearance (0 — off)
nNpcStringId (int) — the number of the ready (localized) phrase to show
sStr1 (string) — the first string substitution into the phrase (for example, the target's name)
sStr2 (string) — the second string substitution
sStr3 (string) — the third string substitution
sStr4 (string) — the fourth string substitution
sStr5 (string) — the fifth string substitutionExample
BroadcastOnScreenMsgFStr(myself.sm, 8000, 2, 0, 0, 0, 0, 1, 10000, 0, 1100223, "", "", "", "", "");Usage example
if ( IsNullCreature( c3 ) == 0 ) {
BroadcastOnScreenMsgFStr( myself.sm, 4000, 1, 0, 0, 0, 0, 0, 3000, 0, 1000519, c3.name, _blank, _blank, _blank, _blank );
}BroadcastOnScreenMsgStrGLOBAL🟢 high
Displays large text on the screen to players within a radius using an arbitrary string. The function is
a thin forwarder: the NPC server checks the radius and forwards the fields to the main server,
which builds the client packet ExShowScreenMessage. Position, font size, effect,
display time, and fade are set by numeric parameters (confirmed by the engine source).
Signature
BroadcastOnScreenMsgStr( CSharedCreatureData cCreature, int nRange, int nMsgPosType, int nParam1, int nFontSize, int nParam2, int nParam3, int nEffect, int nTime, int nFade, string sMsg )
Parameters (confirmed by the engine source — the on-screen message handler builds the client
packet ExShowScreenMessage; the message type is fixed = 1 "arbitrary text"):
cCreature (CSharedCreatureData) — the source creature; its id is the recipient, and its position is the broadcast center.
nRange (int) — the broadcast radius; checked on the NPC server side (0..16384). 4000 in calls.
nMsgPosType (int) — the message position on the screen. 2 in calls.
nParam1 (int) — a service packet field (unnamed in the engine, nParam1). 0 in calls.
nFontSize (int) — font size. 0 in calls (default).
nParam2 (int) — a service packet field (unnamed in the engine, nParam2). 0 in calls.
nParam3 (int) — a service packet field (unnamed in the engine, nParam3). 0 in calls.
nEffect (int) — the text's visual appearance effect. 1 in calls.
nTime (int) — display duration on screen, ms. 3000 in calls.
nFade (int) — fade effect (smooth disappearance). 0 in calls.
sMsg (string) — the text to display.Example
BroadcastOnScreenMsgStr( myself.sm, 4000, 2, 0, 0, 0, 0, 1, 3000, 0, MakeFString( 1000527, _blank, _blank, _blank, _blank, _blank ) );BroadcastOnScreenNpcStringGLOBAL🟢 high
The same as BroadcastOnScreenMsgFStr: large text over the screen to all players around the
source, with the same layout of numeric fields (caption position, appearance effect, display
time, fade). The only difference is the text source — here the phrase is taken from the NPC's
string set by its number nNpcStringId, with substitutions sStr1..sStr5. Returns nothing.
Signature
BroadcastOnScreenNpcString( CSharedCreatureData c, int nRange, int nMsgPosType, int nParam1, int nFontSize, int nParam2, int nParam3, int nEffect, int nTime, int nFade, int nNpcStringId, string sStr1, string sStr2, string sStr3, string sStr4, string sStr5 )Parameters
c (CSharedCreatureData) — the source creature; the circle whose players see the caption is measured around it
nRange (int) — visibility radius in game units: how far from the source the text is still shown (maximum 16384)
nMsgPosType (int) — where on the screen to place the caption (a code designation of the screen zone; 2 in calls)
nParam1 (int) — a service output field (0 in calls)
nFontSize (int) — font size (0 — default size)
nParam2 (int) — a service output field (0 in calls)
nParam3 (int) — a service output field (0 in calls)
nEffect (int) — the caption's appearance effect (0 — no effect, 1 — with effect)
nTime (int) — how long to keep the caption on screen, milliseconds (10000 in calls)
nFade (int) — smooth fade on disappearance (0 — off)
nNpcStringId (int) — the number of the NPC string to show
sStr1 (string) — the first string substitution into the phrase (for example, the player's name)
sStr2 (string) — the second string substitution
sStr3 (string) — the third string substitution
sStr4 (string) — the fourth string substitution
sStr5 (string) — the fifth string substitutionExample
BroadcastOnScreenNpcString( myself.sm, 16384, 2, 0, 0, 0, 0, 1, 10000, 0, 1100292, talker.name, _blank, _blank, _blank, _blank );MakeAttackEventNPC🟢 high
Initiates a combat reaction of the NPC to the creature c as if it had dealt damage dDamage:
adds hate and starts an attack. Takes CSharedCreatureData c, float
dDamage, and int nIsParty (no namespace), returns nothing; with nIsParty=1 the aggro
spreads to the target's whole party, with 0 — only to the target itself.
Signature
MakeAttackEvent( CSharedCreatureData cCreature, float dDamage, int nIsParty )Parameters
cCreature (CSharedCreatureData) — the target of the combat reaction.
dDamage (float) — the weight of the "damage"/hate.
nIsParty (int) — 1 = to the target's whole party, 0 = only to the target.Example
MakeAttackEvent(c1, 100, 0);Usage example
if ( i0 == 1 ) {
MakeAttackEvent( h0.creature, 100, 0 );
}BroadcastScriptEventNPC🟢 high
Broadcasts the script event nEventId with the data nParam to all NPCs within the radius nDist,
each recipient handles it in SCRIPT_EVENT. Takes int nEventId, int
nParam, and int nDist (no namespace), returns nothing. A classic — calling for
help: "I was attacked, the target is this index".
Related event: the addressees catch SCRIPT_EVENT(script_event_arg1..3) (see NASC_HANDLERS).
Signature
BroadcastScriptEvent( int nParam1, int nParam2, int nDist )Parameters
nParam1 (int) — the event id (a script constant).
nParam2 (int) — the data (often GetIndexFromCreature(attacker)).
nDist (int) — the broadcast radius.Example
BroadcastScriptEvent( @NAVIT_DESPAWN2, 0, 500 );Usage example
if ( myself.top_desire_target == attacker ) {
BroadcastScriptEvent( 10016, GetIndexFromCreature( attacker ), 300 );
}BroadcastScriptEventExNPC🟢 high
An extended version of the broadcast event, carrying two data fields nParam2 and
nParam3. Takes int nEventId, int nParam2, int nParam3, and int nDist (no
namespace), returns nothing.
Related event: the addressees catch SCRIPT_EVENT(script_event_arg1..3) (see NASC_HANDLERS).
Signature
BroadcastScriptEventEx( int nParam1, int nParam2, int nParam3, int nDist )Parameters
nParam1 (int) — the event id.
nParam2 (int) — data 1.
nParam3 (int) — data 2.
nDist (int) — the broadcast radius.Example
BroadcastScriptEventEx(@SCE_PHASE_END, 1, 0, 4000);Usage example
if ( i2 != NumberOfCircle ) {
BroadcastScriptEventEx( i2, 30003, 0, 10000 );
}BroadcastScriptEventCondNPC🟢 high
The same extended broadcast with two data fields, additionally filtering
recipients by a condition (probably by the NPC's type/state); the exact meaning of the differences is not
confirmed. Takes int nEventId, int nParam2, int nParam3, and int nDist (no
namespace), returns nothing.
Related event: the addressees catch SCRIPT_EVENT(script_event_arg1..3) (see NASC_HANDLERS).
Signature
BroadcastScriptEventCond( int nParam1, int nParam2, int nParam3, int nDist )Parameters
nParam1 (int) — the identifier of the broadcast event (the event code)
nParam2 (int) — the first payload field of the event
nParam3 (int) — the second payload field of the event
nDist (int) — the broadcast radius: the distance within which the event is receivedExample
BroadcastScriptEventCond(@SCE_BELETH_DESPAWN, 0, 0, 4000);BroadcastSystemMessageNPC🟢 high
Broadcasts a system message by the identifier nSysMsgId to players within the radius nDist
(a system-chat line). Takes CSharedCreatureData c, int nSysMsgId, and int
nDist (no namespace), returns an int.
Signature
BroadcastSystemMessage( CSharedCreatureData cCreature, int nSysMsgId, int nDist )Parameters
cCreature (CSharedCreatureData) — the source creature relative to which the broadcast radius is determined
nSysMsgId (int) — the identifier of the system message to show
nDist (int) — the broadcast radius: the distance (0..16384) within which the message is seenExample
BroadcastSystemMessage(myself.sm, 0, 6503);Usage example
if ( GetSSQSealOwner( 1 ) == 1 ) {
BroadcastSystemMessage( myself.sm, 0, 1215 );
}BroadcastSystemMessageStrNPC🟢 high
Shows a system message (a line in system chat) with the arbitrary text
sText to all players around the source. The message is seen by those within the
radius nDist from the source creature; beyond that circle the text does not arrive. The text is usually
prepared in advance — via MakeFString with substitutions — and passed as an already-assembled
string. Used for "across the whole courtyard" notifications: congratulations, announcements about the progress of an
event. Returns nothing.
Signature
BroadcastSystemMessageStr( CSharedCreatureData cCreature, int nDist, string sText )Parameters
cCreature (CSharedCreatureData) — the source creature; the circle whose players receive the message is measured around it
nDist (int) — the audibility radius in game units: how far from the source the message is still seen (maximum 16384; 0 — minimal coverage right at the source)
sText (string) — the ready message text (an arbitrary string or the result of MakeFString)Example
BroadcastSystemMessageStr(myself.sm, 8000, s0);
BroadcastSystemMessageStr(myself.sm, 0, "Wow! " + myself.master.name + " " + s1 + "!" );
BroadcastSystemMessageStr(myself.sm, 0, MakeFString(1900027, c0.name, "", "", "", ""));
BroadcastSystemMessageStr(myself.sm, 2000, MakeFString(1800881, "", "", "", "", ""));Usage example
if (i0 <= i1) {
BroadcastSystemMessageStr(myself.sm, range_to_yell, MakeFString(yell_congratz01, myself.c_ai0.name, "", "", "", ""));
BroadcastOnScreenMsgStr(myself.sm, range_to_yell, 5, 0, 1, 3, 1, 1, 5000, 0, MakeFString(yell_congratz01, myself.c_ai0.name, "", "", "", ""));
} else {
BroadcastSystemMessageStr(myself.sm, range_to_yell, MakeFString(yell_congratz02, myself.c_ai0.name, "", "", "", ""));
BroadcastOnScreenMsgStr(myself.sm, range_to_yell, 5, 0, 1, 3, 1, 1, 5000, 0, MakeFString(yell_congratz02, myself.c_ai0.name, "", "", "", ""));
}BroadcastSystemMessageFStrNPC🟢 high
The same as BroadcastSystemMessageStr, but the text is taken not as an arbitrary string, but by the
number of a ready (already translated) phrase nNpcStringId. This phrase has slots for
substitutions — they are filled with the strings pStr1..pStr5 (the target's name, a number, etc.); the extra
ones are left empty. The message is shown as a system line to all players within the
radius nDist from the source. Returns nothing.
Signature
BroadcastSystemMessageFStr( CSharedCreatureData cCreature, int nDist, int nNpcStringId, string pStr1, string pStr2, string pStr3, string pStr4, string pStr5 )Parameters
cCreature (CSharedCreatureData) — the source creature; the circle whose players receive the message is measured around it
nDist (int) — the audibility radius in game units: how far from the source the message is still seen (maximum 16384)
nNpcStringId (int) — the number of the ready (localized) phrase to show
pStr1 (string) — the first string substitution into the template (in place of [p1])
pStr2 (string) — the second string substitution (in place of [p2])
pStr3 (string) — the third string substitution (in place of [p3])
pStr4 (string) — the fourth string substitution (in place of [p4])
pStr5 (string) — the fifth string substitution (in place of [p5])Example
BroadcastSystemMessageFStr(myself.sm, 1500, Message_ID, "", "", "", "", "");
BroadcastSystemMessageFStr(myself.sm, 1500, 1100153, "", "", "", "", "");
BroadcastSystemMessageFStr(myself.sm, 1500, 1100139, "", "", "", "", "");
BroadcastSystemMessageFStr(myself.sm, 1500, i4, target.name, IntToStr(i5), "", "", "");Usage example
if ( NeedShoutSA ) {
BroadcastSystemMessageFStr( myself.sm, 2500, i4, target.name, IntToStr( i5 ), _blank, _blank, _blank );
}PARTIES AND CLANS (Party / Pledge)
24 functionsGetPartyGLOBAL🟢 high
Returns the party object in which the creature c is a member, or empty/null
if the creature is not in a party (checked via IsNullParty). Takes a creature
CSharedCreatureData; a function of the global object gg. Returns a CSharedPartyData.
Signature
GetParty( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — whose party we get.Example
party0 = GetParty( c3 );Usage example
party0 = GetParty( target );
if ( IsNullParty( party0 ) ) {
return;
} else {
TeleportParty( party0.id, SibylPosX, SibylPosY, SibylPosZ, 300, ( part_type * RoomIndex ) );
}Party_GetCountGLOBAL🟢 high
Returns the number of members in the creature c's party; this is the basis for iterating a party in a loop. If
the creature is not in a party — usually 0 or 1. Takes a creature CSharedCreatureData;
a function of the global object gg. Returns an integer.
Signature
Party_GetCount( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — whose party.Example
i1 = Party_GetCount( c1 );Party_GetCreatureGLOBAL🟢 high
Returns a member of the creature c's party by index nIndex (zero-based). Together with
Party_GetCount it gives an iteration over all party mates — for example, to give a reward or a buff
to the whole party. Takes a creature CSharedCreatureData and an integer index
(0..count-1); a function of the global object gg. Returns a CSharedCreatureData.
Signature
Party_GetCreature( CSharedCreatureData cCreature, int nIndex )Parameters
cCreature (CSharedCreatureData) — whose party.
nIndex (int) — the member index (0..count-1).Example
c0 = Party_GetCreature( c1, i0 );Usage example
c1 = Party_GetCreature( talker, i2 );
if ( OwnItemCount( c1, @q_antique_brooch ) == 0 ) {
GiveItem1( c1, @q_used_adm_to_grave, 1 );
}Party_GetLeaderGLOBAL🟢 high
Returns the leader of the party in which the creature c is a member. Convenient when you have a
player at hand. Takes a creature CSharedCreatureData; a function of the global object gg.
Returns a CSharedCreatureData.
Signature
Party_GetLeader( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature by whose party the leader is searchedExample
c0 = Party_GetLeader( c0 );
c0 = Party_GetLeader( talker );
c1 = Party_GetLeader(talker);Usage example
if ( Party_GetLeader( talker ) != talker ) {
ShowPage( talker, "ssq_main_event_sibyl_q0505_04.htm" );
} else {
ShowPage( talker, "ssq_main_event_sibyl_q0505_01.htm" );
}GetTopDamageCreatureGLOBAL🟢 high
Returns the single creature that dealt the creature c (usually a raid boss) the greatest
total damage. Applied on a boss's death to distribute the reward to whoever fought
hardest. Takes a creature CSharedCreatureData; a function of the global objectgg. Returns a CSharedCreatureData.
Signature
GetTopDamageCreature( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the creature (usually a raid boss) for which the top-damage dealer is searched
Example (illustrative):
GetTopDamageCreature( talker );GetTopDamagePartyGLOBAL🟢 high
Returns the party that dealt the creature c the greatest total damage. The
aggregation level of the damage is a single party; used when distributing the reward for a boss fight.
Takes a creature CSharedCreatureData; a function of the global object gg. Returns a
CSharedPartyData.
Signature
GetTopDamageParty( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the creature by whose damage the party that damaged it most is determined
Example (illustrative):
GetTopDamageParty( talker );GetTopDamageMpccGLOBAL🟢 high
Returns the command channel (MPCC — a union of several parties) that dealt the creature c
the greatest total damage. The senior level of damage aggregation when distributing the reward for a
raid-boss fight. Takes a creature CSharedCreatureData; a function of the global object gg.
Returns a CSharedGeneralObjectData.
Signature
GetTopDamageMpcc( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the creature by whose damage the command channel (MPCC) that damaged it most is determined
Example (illustrative):
GetTopDamageMpcc( talker );GetLeaderOfPartyNPC🟢 high
Returns a party's leader by the party object p itself. Applied when you only have a
CSharedPartyData — for example, one obtained from GetTopDamageParty. Takes a party object
CSharedPartyData; an NPC function (myself). Returns a CSharedCreatureData.
Signature
GetLeaderOfParty( CSharedPartyData p )Parameters
p (CSharedPartyData) — the party object whose leader is taken.Example
c0 = GetLeaderOfParty(lparty);Usage example
c1 = GetLeaderOfParty( party0 );
if ( IsNullCreature( c1 ) == 0 ) {
Shout( MakeFString( 1010634, c1.name, IntToStr( i2 ), "", "", "" ) );
}Party_GetMemberNPC🟢 high
Returns a party member by numeric identifiers. Per the L2NPC decompile
(CNPC::Party_GetMember_4A79A8) the first argument is the party id (its low 20 bits
index the party array), the second is the member index, limited by the engine to the range 0..9.
It then calls the same code as GetMemberOfParty. An NPC function (myself). Returns a
CSharedCreatureData.
Signature
Party_GetMember( int nPartyId, int nIndex )Parameters
nPartyId (int) — the party id (party0.id; in calls also myself.i_quest0 with a saved id).
nIndex (int) — the member index in the party, 0..9.Example
c0 = Party_GetMember(i2, i9);Usage example
c3 = Party_GetMember( myself.i_quest0, i8 );
if ( IsNullCreature( c3 ) == 0 ) {
ShowOnScreenMsgStr( c3, 2, 0, 0, 0, 1, 0, 10000, 0, s0 );
}GetMemberOfPartyNPC🟢 high
Returns a member of the party p by index nIndex. Applied when you only have a party
object CSharedPartyData. Takes a party object CSharedPartyData and an integer index;
an NPC function (myself). Returns a CSharedCreatureData.
Signature
GetMemberOfParty( CSharedPartyData p, int nIndex )Parameters
p (CSharedPartyData) — the party object from which the member is taken.
nIndex (int) — the member index in the party.Example
c3 = GetMemberOfParty( party0, i8 );Usage example
target = GetMemberOfParty( lparty, i9 );
if ( HaveMemo( target, @relics_of_the_old_empire ) == 1 ) {
random1_list.SetInfo( 0, target );
}IsMemberOfPartyNPC🟢 high
Checks whether the creature c is a member of the party p (returns 1 or 0). Serves for
the "friend/foe" logic in group scenes. Takes a creature CSharedCreatureData and a party
object CSharedPartyData; an NPC function (myself). Returns an integer.
Signature
IsMemberOfParty( CSharedCreatureData c, CSharedPartyData p )Parameters
c (CSharedCreatureData) — whom we check.
p (CSharedPartyData) — in which party.
Example (illustrative):
IsMemberOfParty( talker, party0 );GetPledgeNPC🟢 high
Returns the clan (pledge) object in which the creature c is a member. This is the starting point
of all clan operations — the treasury, ranks, war registration. Takes a creature
CSharedCreatureData; an NPC function (myself). Returns a CSharedPledgeData.
Signature
GetPledge( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — whose clan.Example
pledge0 = GetPledge(talker);Usage example
pledge0 = GetPledge( last_attacker );
if ( IsNull( pledge0 ) == 1 ) { return; }HavePledgePowerNPC🟢 high
Checks whether the player c has the clan privilege nPledgePower (returns 1 or0). Privileges are given by @-constants (@ppSetGate, @PP_OPEN_CASTLE_DOOR,@ppRegisterWar, @PP_USE_AGIT_FUNC, etc.). This is how castle and clan NPCs decide
whether the player is entitled to open a door, register a war, manage a clan hall. Takes
a creature CSharedCreatureData and an integer privilege code; an NPC function (myself).
Returns an integer.
Signature
HavePledgePower( CSharedCreatureData c, int nPledgePower )Parameters
c (CSharedCreatureData) — the player.
nPledgePower (int) — the code of the clan privilege being checked (manual_pch; the current numbering):
1 @PP_JOIN clan recruitment, 2 @PP_GIVE_NICKNAME/@ppGiveTitle title, 3 @PP_VIEW_WAREHOUSE warehouse,
4 @PP_MANAGE_GRADE ranks, 5 @PP_DECLARE_WAR war, 6 @PP_OUST_MEMBER expulsion,
7 @PP_SET_CREST crest, 8 @PP_MANAGE_MASTER unit leaders, 9 @PP_MANAGE_GROWTH/@ppSubPledgeMaster,
10 @PP_SUMMON_AIRSHIP, 11 @PP_OPEN_AGIT_DOOR/@ppGateOpen clan hall doors, 12 @PP_USE_AGIT_FUNC/@ppDecoFunction,
13 @PP_AGIT_AUCTION clan hall auction, 14 @PP_OUST_FROM_AGIT/@ppClanHallBanish, 15 @PP_CONTROL_AGIT_FUNC/@ppManage,
16 @PP_OPEN_CASTLE_DOOR/@ppSetGate castle doors, 17 @PP_MANAGE_MANOR/@ppManor manor,
18 @PP_REGISTER_CASTLE_WAR/@ppSiege siege, 19 @PP_USE_CASTLE_FUNC/@ppCastleShop, 20 @PP_OUST_FROM_CASTLE/@ppBanish,
21 @PP_MANAGE_TAX/@ppTaxVault tax/treasury, 22 @PP_MANAGE_MERCENARY mercenaries, 23 @PP_CONTROL_CASTLE_FUNC/@ppSiegeDefend,
24 @PP_USE_THRONE_OF_HERO throne. The numbers are shifted in early chronicles (see manual_pch, the "IL" labels).Example
if (HavePledgePower(talker, @ppDecoFunction) && Castle_GetPledgeId() == talker.pledge_id && talker.pledge_id != 0)Usage example
if ( IsMyLord( talker ) || ( HavePledgePower( talker, @ppGateOpen ) && Castle_GetPledgeId( ) == talker.pledge_id && talker.pledge_id != 0 ) ) {
ShowPage( talker, fnDoor );
} else {
ShowPage( talker, fnNoAuthority );
}GetPledgeMemberCountNPC🟢 high
Returns the number of members of the clan in which the creature c is a member. Used in clan
dialogs and conditions. Takes a creature CSharedCreatureData; an NPC function (myself).
Returns an integer.
Signature
GetPledgeMemberCount( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature by whose clan the member count is calculatedExample
i0 = GetPledgeMemberCount(talker);Usage example
if ( GetPledgeMemberCount(talker) >= 40 ) { // orig >= 140
UpdatePledgeNameValue( talker, -100000 );
DeleteItem1( talker, item_lvup10 , num_item_lvup10 );
PledgeLevelUp( talker, 10 );
AddUseSkillDesire(talker, EffectSkill1, @ST_HEAL, @AMT_STAND, 1000000);
ShowPage( talker, "pl_err_total_member.htm" );
}GetPledgeMoneyNPC🟢 high
In meaning it returns the adena of the creature c's clan treasury. IMPORTANT: in the NPC build the function is actually a STUB — under any circumstances it returns 0 (no clan — 0; there is a clan —
still 0, the money field is not read). The real treasury amount is known only to the server side
(L2Server), so in NPC AI scripts this result cannot be relied upon. The units are adena
(a 32-bit integer). Takes a creature CSharedCreatureData; an NPC function (myself).
Signature
GetPledgeMoney( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature by whose clan the treasury (clan money) is taken
Example (illustrative):
GetPledgeMoney( talker );Pledge_GetCountNPC🟢 high
Returns the clan counter of the creature c (a basic clan datum). Used in
clan dialogs and conditions. Takes a creature CSharedCreatureData; an NPC function
(myself). Returns an integer.
Signature
Pledge_GetCount( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature by whose clan the counter is taken
Example (illustrative):
Pledge_GetCount( talker );Pledge_GetLeaderNPC🟢 high
Returns the leader of the clan in which the creature c is a member. Used in clan
dialogs and conditions. Takes a creature CSharedCreatureData; an NPC function (myself).
Returns a CSharedCreatureData.
Signature
Pledge_GetLeader( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature by whose clan the clan leader is searchedExample
c2 = Pledge_GetLeader( c1 );Usage example
c2 = Pledge_GetLeader( c1 );
if ( IsNullCreature( c2 ) == 0 ) {
if ( HaveMemo( c2, @pursuit_of_clan_ambition ) == 1 && GetMemoState( c2, @pursuit_of_clan_ambition ) < 8511 && GetMemoState( c2, @pursuit_of_clan_ambition ) >= 8500 && DistFromMe( c2 ) <= 1500 ) {
CreateOnePrivate( @imperial_coffer, "imperial_coffer", 0, 1 );
}
}HasSubPledgeNPC🟢 high
Checks whether the creature c's clan has a sub-unit of type nType (knights, academy,
royal guard). Returns 1 if such a sub-unit is created, otherwise 0. Per decompile it takes the creature's
clan (no clan — 0), converts the type into an internal index (0..7), and checks the corresponding
bit in the mask of the clan's existing sub-units — that is, up to eight sub-unit types. The exact
"type → index" table lies in the engine data. Takes a creature CSharedCreatureData and
an integer unit type.
Signature
HasSubPledge( CSharedCreatureData c, int nType )Parameters
c (CSharedCreatureData) — the creature by whose clan the presence of a sub-unit is checked.
nType (int) — the sub-unit type (enum PledgeType, from manual_pch):
-1 @ACADEMY academy, 100 @ROYAL_GUARD_1, 200 @ROYAL_GUARD_2,
1001 knight 1, 1002 knight 2, 2001 knight 3, 2002 knight 4.Example
if (HasSubPledge(talker, @ROYAL_GUARD_1) == @TRUE)Usage example
if (HasSubPledge(talker, i0) == 1) {
ShowPage(talker, "pl_err_fame.htm");
return;
}MPCC_GetPartyIDNPC🟢 high
By the key mpcc_id and the ordinal index party_index returns the party ID in a multi-party command channel. Called on an NPC object.
Signature
MPCC_GetPartyID( int nMpccId, int nPartyIndex )Parameters
nMpccId (int) — the command channel identifier (mpcc_id).
nPartyIndex (int) — the ordinal index of the party in the channel.Example
i1 = MPCC_GetPartyID( i0, 0 );MPCC_GetMPCCIdNPC🟢 high
Returns the ID of the command channel the creature is in. Called on an NPC object.
Signature
MPCC_GetMPCCId( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature whose command channel is requestedExample
i0 = MPCC_GetMPCCId( talker );Usage example
i3 = MPCC_GetMPCCId( talker );
if ( i3 > 0 ) {
i4 = MPCC_GetMemberCount( i3 );
if ( i4 >= 55 ) {
SendScriptEvent( c0, 99999999, i3 );
}
}MPCC_SetMasterPartyRoutingNPC🟢 high
Enables or resets the master-party routing of a command channel. Per the L2NPC decompile it
sends the server a packet opcode 124; the handler (L2Server: NpcSetMPCCMasterPartyRouting_731E6C)
chooses the action by the flag: 1 — set master-party routing (SetMasterPartyRouting),
0 — reset it (ResetMasterPartyRouting, if this channel was the routing one). No return.
Signature
MPCC_SetMasterPartyRouting( int nMpccId, CSharedCreatureData cMaster, int nOnOff )Parameters
nMpccId (int) — the command channel identifier (mpcc_id).
cMaster (CSharedCreatureData) — the creature — the master party's leader.
nOnOff (int) — 1 = set master-party routing; 0 = reset the routing.Example
MPCC_SetMasterPartyRouting( script_event_arg2, myself.sm, 1 );Usage example
if ( c0.db_value == 0 ) {
MPCC_SetMasterPartyRouting( myself.i_ai1, c0, 0 );
SendScriptEvent( c0, @SCE_ANTARAS_PC_ENTERED, 0 );
}MPCC_GetMasterNPC🟢 high
By the key mpcc_id returns the creature — the leader of the command channel's master party. Called on an NPC object.
Signature
MPCC_GetMaster( int nMpccId )Parameters
nMpccId (int) — the command channel identifier (mpcc_id).Example
c0 = MPCC_GetMaster( i0 );
c1 = MPCC_GetMaster( i9 );
c1 = MPCC_GetMaster( i1 );
c3 = MPCC_GetMaster( i3 );Usage example
c0 = MPCC_GetMaster( i0 );
if ( IsNullCreature( c0 ) ) { c0 = target; } // if the player somehow dropped out of the CC and the leader is not foundMPCC_GetMemberCountNPC🟢 high
By the key mpcc_id returns the total number of members in the command channel.
Signature
MPCC_GetMemberCount( int nMpccId )Parameters
nMpccId (int) — the command channel identifier (mpcc_id).Example
i4 = MPCC_GetMemberCount( i3 );
i2 = MPCC_GetMemberCount(i1);Usage example
i4 = MPCC_GetMemberCount( i3 );
if ( i4 >= 55 ) {
SendScriptEvent( c0, 99999999, i3 );
}MPCC_GetPartyCountNPC🟢 high
By the key mpcc_id returns the number of parties in the command channel. Called on an NPC object.
Signature
MPCC_GetPartyCount( int nMpccId )Parameters
nMpccId (int) — the command channel identifier (mpcc_id).Example
i7 = MPCC_GetPartyCount( i0 );Usage example
i1 = MPCC_GetPartyCount( i0 );
if ( i1 < 7 ) {
ShowPage( talker, "zaken_enter001d.htm" );
}Academy
6 functionsIsAcademyMemberNPC🟢 high
Returns whether the player cCreature is a member of the clan academy as a student (1/0, compared with @TRUE), namespace CNPC.
Signature
IsAcademyMember( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose membership in the clan academy is checkedExample
if (_from_choice == 0 || (HaveMemo(talker, @one_who_leads_one_who_is_led) == @FALSE && HaveMemo(talker, @one_who_leads_one_who_is_led_2) == @FALSE && talker.level >= 19 && IsAcademyMember(talker) == @TRUE && HasAcademyMaster(talker) == @TRUE && GetOneTimeQuestFlag(talker, @one_who_leads_one_who_is_led_2) == @FALSE && GetOneTimeQuestFlag(talker, @one_who_leads_one_who_is_led) == @FALSE))Usage example
if( IsAcademyMember( talker ) == 1 ) {
GiveItem1( talker, @academy_circlet ,1 );
ShowSystemMessage( talker,1749 );
}HasAcademyMasterNPC🟢 high
Returns whether the player cCreature has a mentor in the academy (1/0), namespace CNPC.
Signature
HasAcademyMaster( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose presence of an academy mentor is checkedExample
if ( HaveMemo( talker, @to_lead_and_be_led ) == 0 && HaveMemo( talker, @one_who_leads_one_who_is_led_2 ) == 0 && talker.level >= 19 && IsAcademyMember( talker ) == 1 && HasAcademyMaster( talker ) == 1 && GetOneTimeQuestFlag( talker, @to_lead_and_be_led ) == 0 && GetOneTimeQuestFlag( talker, @one_who_leads_one_who_is_led_2 ) == 0 ) {Usage example
if ( _from_choice == 0 || ( ( ( HaveMemo( talker, @to_lead_and_be_led ) == 0 && HaveMemo( talker, @one_who_leads_one_who_is_led_2 ) == 0 && ( talker.level < 19 || IsAcademyMember( talker ) == 0 || HasAcademyMaster( talker ) == 0 ) ) && GetOneTimeQuestFlag( talker, @one_who_leads_one_who_is_led_2 ) == 0 ) && GetOneTimeQuestFlag( talker, @to_lead_and_be_led ) == 0 ) ) {
SetCurrentQuestID( @one_who_leads_one_who_is_led_2 );
ShowQuestPage( talker, "head_blacksmith_newyear_q0123_02.htm", @one_who_leads_one_who_is_led_2 );
}GetAcademyMasterNPC🟢 high
Returns the player cCreature's mentor in the academy (a creature), namespace CNPC.
Signature
GetAcademyMaster( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose academy mentor is to be obtainedExample
c0 = GetAcademyMaster( talker );
c0 = GetAcademyMaster( target );HasAcademyMemberNPC🟢 high
Returns whether the player cCreature has a student in the academy (1/0, compared with @TRUE), namespace CNPC.
Signature
HasAcademyMember( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`cCreature`) whose presence of an academy student is checkedExample
if (_from_choice == 0 || HasAcademyMember(talker) == @TRUE)Usage example
if ( HasAcademyMember( talker ) == 1 ) {
_choiceN = ( _choiceN + 1 );
_code = 15;
AddChoice( 15, MakeFString( 11804, _blank, _blank, _blank, _blank, _blank ) ); // To Lead And Be Led (Sponsor)
}GetAcademyMemberNPC🟢 high
Returns the player cCreature's student in the academy (a creature), namespace CNPC.
Signature
GetAcademyMember( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`cCreature`) whose academy student is returnedExample
c0 = GetAcademyMember( talker );HasAcademyNPC🟢 high
Returns whether the player cCreature has an academy (1/0, compared with @TRUE), namespace CNPC. The exact difference from HasAcademyMaster/HasAcademyMember is not fully confirmed.
Signature
HasAcademy( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`cCreature`) whose presence of an academy is checkedExample
if ( HasAcademy( talker) == @TRUE ) {Usage example
if ( HasAcademy( talker) == 1 ) {
ShowPage( talker, "pl_err_aca.htm" );
} else {
ShowPage( talker, "pl_err_aca.htm" );
}Player: name & status (Player)
10 functionsGetCountryGLOBAL🟢 high
Returns the numeric country/region code of the player cCreature (int), namespace gg. Used for localization (choosing the right .htm or text).
Signature
GetCountry( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player for whom the country/region code is returnedExample
if (GetCountry(talker) == 2) { ShowNewTutorialHTML(talker, "..\L2text\pet_visual26-ua.htm"); }Usage example
if (GetCountry(talker) == 2) { ShowNewTutorialHTML(talker, "..\L2text\pet_visual26-ua.htm"); }
else if (GetCountry(talker) == 4) { ShowNewTutorialHTML(talker, "..\L2text\pet_visual26-cn.htm"); }
else if (GetCountry(talker) == 8) { ShowNewTutorialHTML(talker, "..\L2text\pet_visual26-ru.htm"); }
else { ShowNewTutorialHTML(talker, "..\L2text\pet_visual26-eu.htm"); }ChangeNickNameNPC🟢 high
Changes the creature cCreature's title — the string above its head — to sName, namespace CNPC.
Signature
ChangeNickName( CSharedCreatureData pCreatureShared, string sName )Parameters
pCreatureShared (CSharedCreatureData) — the creature whose title above its head is changed
sName (string) — the new title textExample
case 1: { ChangeNickName(myself.sm, LocationName_01); break; }ChangeMasterNameNPC🟢 high
Changes the "second line" / owner name of the creature cCreature to sName, namespace CNPC.
Signature
ChangeMasterName( CSharedCreatureData pCreatureShared, string sName )Parameters
pCreatureShared (CSharedCreatureData) — the creature whose owner name (the second line) is changed
sName (string) — the new owner name textExample
ChangeMasterName(myself.sm, "DEAD * RESPAWN IN " + IntToStr(myself.i_ai3) + " MIN");ChangeFStrNickNameNPC🟢 high
Changes the creature cCreature's title to localizable text by the phrase id nFStringId with the parameter sParam, namespace CNPC.
Signature
ChangeFStrNickName( CSharedCreatureData cCreature, int nArg1, string pStr1 )Parameters
cCreature (CSharedCreatureData) — the creature whose title is changed
nArg1 (int) — the id of the localizable phrase for the title (`nFStringId`)
pStr1 (string) — the substitution parameter into the phrase (`sParam`)Example
ChangeFStrNickName(myself.sm, 1801100, IntToFStr(i1));Usage example
if ( i0 >= 60008 && i0 <= 60011 ) {
ChangeFStrNickName( myself.sm, i0, "" );
}ChangeFStrMasterNameNPC🟢 high
Changes the creature cCreature's name "second line" to localizable text by the phrase id nFStringId with the parameter sParam, namespace CNPC.
Signature
ChangeFStrMasterName( CSharedCreatureData cCreature, int nArg1, string pStr1 )Parameters
cCreature (CSharedCreatureData) — the creature whose name second line is changed
nArg1 (int) — the id of the localizable phrase for the second line (`nFStringId`)
pStr1 (string) — the substitution parameter into the phrase (`sParam`)Example
ChangeFStrMasterName(myself.sm, 1100159, _blank);IsNewbieNPC🟢 high
Returns whether the player cCreature is considered a newbie (1/0), namespace CNPC.
Signature
IsNewbie( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`cCreature`) checked for newbie statusExample
if ( IsNewbie( talker ) ) {Usage example
if ( talker.level < 25 && IsNewbie( talker ) && IsInCategory( @fighter_group, talker.occupation ) ) {
GiveItem1( talker, @soulshot_none_for_rookie, 7000 );
VoiceEffect( talker, "tutorial_voice_026", 1000 );
}SetNoblessNPC🟢 high
Assigns the player cCreature noblesse status, namespace CNPC.
Signature
SetNobless( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`cCreature`) assigned noblesse statusExample
SetNobless( talker );SetHeroNPC🟢 high
Assigns the player cCreature hero status, namespace CNPC.
Signature
SetHero( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`cCreature`) assigned hero statusExample
SetHero( talker );Usage example
if ( talker.hero_type == 1 ) {
SetHero( talker );
}
Related event: the server's response arrives as the SET_HERO_RETURNED event (see NASC_HANDLERS).GetHwidNPC🟢 high
Returns the HWID — a string identifier of the player cCreature's hardware (string), namespace CNPC. There are few calls, the string format is weakly confirmed.
Signature
GetHwid( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the player (`cCreature`) whose HWID is returnedExample
if(IsSameString(myself.str_list.Get(i0), GetHwid(talker)))Usage example
if(IsSameString(myself.str_list.Get(i0), GetHwid(talker)))
{
ShowPage(talker, "atb_event_hw_portal_03.htm");
return;
}ShowChangePledgeNameUINPC🟢 high
Opens for the player cCreature the clan name change window, namespace CNPC.
Signature
ShowChangePledgeNameUI( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`cCreature`) for whom the clan name change window is openedExample
ShowChangePledgeNameUI( talker );Usage example
if ( talker.is_pledge_master == 1 ) {
ShowChangePledgeNameUI( talker );
} else {
ShowPage( talker, "pl_err_master.htm" );
}Pets & summons (Pets)
7 functionsGetSummonNPC🟢 high
Returns the summon or pet summoned by the creature cCreature (of type CSharedCreatureData), namespace CNPC. If there is no summoned one, the result may be empty — it is checked via IsNull*. Used before operations with a pet/summon.
Signature
GetSummon( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose summon/pet is returnedExample
c0 = GetSummon(talker);Usage example
c0 = GetSummon(talker);
if (IsNullCreature(c0) == 0 && skip_chk_summon_pet1 == 1) {
ShowPage(talker, fnEvolutionStopped);
return;
}EvolvePetNPC🟢 high
Turns the player cCreature's pet from a hatchling into an adult form, namespace CNPC. Arguments: nPetDbId — the pet's id in the database, nBabyClassId — the hatchling's class, nEvolveItemId — the evolution item, nGrownClassId — the adult's class, nPetLevel — the pet's level.
Signature
EvolvePet( CSharedCreatureData c, int nPetDbId, int nBabyClassId, int nEvolveItemId, int nGrownClassId, int nPetLevel )Parameters
c (CSharedCreatureData) — the pet's owner player.
nPetDbId (int) — the pet's identifier in the database (usually item0.dbid).
nBabyClassId (int) — the hatchling's class (the initial form).
nEvolveItemId (int) — the evolution item.
nGrownClassId (int) — the pet's adult-form class.
nPetLevel (int) — the pet's level (usually item0.pet_level).Example
EvolvePet( talker, item0.dbid, 1012311, 4422, 1012526, item0.pet_level );
EvolvePet( talker, item0.dbid, 1012312, 4423, 1012527, item0.pet_level );
EvolvePet( talker, item0.dbid, 1012313, 4424, 1012528, item0.pet_level );
EvolvePet(talker, item0.dbid, i2, i1, i3, item0.pet_level);Usage example
if (item0.pet_level >= i4) {
EvolvePet(talker, item0.dbid, i2, i1, i3, item0.pet_level);
ShowPage(talker, fnHi);
SoundEffect(talker, "ItemSound.quest_finish");
} else {
ShowPage(talker, "pet_manager_evolve_no.htm");
}EvolvePetWithSameExpNPC🟢 high
Evolution of the player cCreature's pet into the adult form nGrownClassId with the accumulated experience preserved, namespace CNPC. Unlike EvolvePet, only the final class is passed.
Signature
EvolvePetWithSameExp( CSharedCreatureData c, int nGrownClassId )Parameters
c (CSharedCreatureData) — the pet's owner player.
nGrownClassId (int) — the final class of the pet's adult form.Example
EvolvePetWithSameExp( talker, id_grown_pet1 );DestroyPetNPC🟢 high
Removes the player cCreature's pet, namespace CNPC. Arguments: nPetDbId — the pet's id in the database, nPetLevel — the level (the value -99 sets a special removal case).
Signature
DestroyPet( CSharedCreatureData c, int nPetDbId, int nPetLevel )Parameters
c (CSharedCreatureData) — the pet's owner player.
nPetDbId (int) — the pet's identifier in the database (usually item0.dbid / myself.sm.pet_dbid).
nPetLevel (int) — the pet's level; the special value -99 sets a special removal case.Example
DestroyPet( talker, item0.dbid, item0.pet_level );
DestroyPet( myself.master, myself.sm.pet_dbid, -99 );Usage example
if ( item0 ) {
DestroyPet( talker, item0.dbid, item0.pet_level );
}GetEvolutionIdNPC🟢 high
Returns the numeric identifier of the current evolution (int), namespace CNPC. There are almost no calls in our scripts, the semantics is weakly confirmed.
Signature
GetEvolutionId( )Parameters
(none — the function is called without arguments)Example
i0 = GetEvolutionId( );Summon_SetOptionNPC🟢 high
Sets an option of a summoned summon and returns an int, namespace CNPC. Arguments: nOption — the option number (0..3), nValue — the value (for option 1 often 900, for 2/3 — 0 or 1).
Signature
Summon_SetOption( int nOption, int nValue )Parameters
nOption (int) — the summon option number (0..3).
nValue (int) — the option value (for option 1 often 900, for 2/3 — 0 or 1).Example
Summon_SetOption( 3, 1 );RideWyvernNPC🟢 high
Seats the player cCreature astride the wyvern nWyvernId (usually @wyvern), namespace CNPC.
Signature
RideWyvern( CSharedCreatureData c, int nWyvernId )Parameters
c (CSharedCreatureData) — the player who is seated astride.
nWyvernId (int) — the wyvern identifier (usually `@wyvern`).
the values are from the [npc_pch] dictionaryExample
RideWyvern(talker, @wyvern);
RideWyvern( talker, 1012621 );Classes & subclasses (Class / Subclass)
7 functionsClassChangeNPC🟢 high
Changes the player cCreature's main class to nClassId and returns an int, namespace CNPC. The class is given by a @-constant (@duelist, @phoenix_knight, @grand_khavatari, etc.) or a number.
Signature
ClassChange( CSharedCreatureData c, int nClassId )Parameters
c (CSharedCreatureData) — the player whose main class is changed.
nClassId (int) — the identifier of the new class (a class @-constant, e.g. @grand_khavatari, or a number).Example
ClassChange( talker, @grand_khavatari );Usage example
if ( ask == -512 ) {
ClassChange( talker, reply );
}ChangeSubJobNPC🟢 high
Makes the specified subclass nSubJobClass active for the player cCreature, namespace CNPC.
Signature
ChangeSubJob( CSharedCreatureData cCreature, int nSubJobClass )Parameters
cCreature (CSharedCreatureData) — the player for whom the subclass is activated
nSubJobClass (int) — the subclass made activeExample
ChangeSubJob( talker, i0 );Usage example
if( talker.alive ) {
ChangeSubJob( talker, @shillien_knight );
}
Related event: the server's response arrives as the SUBJOB_CHANGED event (see NASC_HANDLERS).RenewSubJobNPC🟢 high
Resets or replaces the player cCreature's subclass in the slot nSlot with the class nClassId, namespace CNPC.
Signature
RenewSubJob( CSharedCreatureData c, int nSlot, int nClassId )Parameters
c (CSharedCreatureData) — the player whose subclass is reset/replaced.
nSlot (int) — the subclass slot number.
nClassId (int) — the identifier of the new subclass class.Example
RenewSubJob( talker, i8, 12 );
Related event: the server's response arrives as the SUBJOB_RENEWED event (see NASC_HANDLERS).GetSubJobListNPC🟢 high
Fills the list of subclasses available for the player cCreature to choose for a menu, namespace CNPC. Arguments: nCategory — the category (10/20/...), nState — the state/filter.
Signature
GetSubJobList( CSharedCreatureData c, int nCategory, int nState )Parameters
c (CSharedCreatureData) — the player for whom the subclass list is built.
nCategory (int) — the subclass category (10/20/…; in calls reply-10).
nState (int) — the selection state/filter (0 in calls).Example
GetSubJobList( talker, ( reply - 10 ), 0 );
Related event: the server's response arrives as the SUBJOB_LIST_INFORMED event (see NASC_HANDLERS).IsMainClassNPC🟢 high
Returns whether the player cCreature's main class is currently active (1/0, compared with @TRUE), namespace CNPC.
Signature
IsMainClass( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose main class activity is checkedExample
if ( IsMainClass( talker ) == @TRUE ) {Usage example
if (IsMainClass(talker) == 1 && talker.level >= 81) {
ShowPage(talker, "inzone_frantz_q010296_01.htm");
}CheckSubJobAsMainNPC🟢 high
Checks whether the player cCreature's subclass nSubJobClass can be made the main class, returns an int, namespace CNPC. The return semantics is weakly confirmed.
Signature
CheckSubJobAsMain( CSharedCreatureData cCreature, int nSubJobClass )Parameters
cCreature (CSharedCreatureData) — the player whose subclass is checked
nSubJobClass (int) — the subclass checked for the possibility of becoming the main classExample
CheckSubJobAsMain( talker, i10 );
CheckSubJobAsMain( talker, @judicator );Usage example
if ( myself.av_quest0.CompareExchange( GetIndexFromCreature( talker ), 0 ) == 0 ) {
CheckSubJobAsMain( talker, i10 );
}SetSubJobAsMainNPC🟢 high
Makes the player cCreature's subclass nSubJobClass the main class, namespace CNPC. There are few calls, the behavior is weakly confirmed.
Signature
SetSubJobAsMain( CSharedCreatureData cCreature, int nSubJobClass )Parameters
cCreature (CSharedCreatureData) — the player whose subclass is made the main
nSubJobClass (int) — the subclass converted into the main classExample
SetSubJobAsMain( c0, myself.av_quest1.GetValue() );
SetSubJobAsMain( talker, reply );
SetSubJobAsMain(c0, @judicator);
SetSubJobAsMain( talker, @judicator );Tutorial
5 functionsShowTutorialHTMLNPC🟢 high
Shows the player cCreature a tutorial HTML window from the file sFile (a .htm name), namespace CNPC.
Signature
ShowTutorialHTML( CSharedCreatureData c, string sFile )Parameters
c (CSharedCreatureData) — the player who is shown the tutorial window.
sFile (string) — the tutorial .htm file name (e.g. "tutorial_human_fighter001.htm").Example
ShowTutorialHTML( talker, "tutorial_human_fighter001.htm" );Usage example
if ( talker.occupation == @shillien_oracle ) {
ShowTutorialHTML( talker, "tutorial_22q.htm" );
}ShowTutorialHTML2NPC🟢 high
The same as ShowTutorialHTML, but with a delay and sound. Per the L2NPC decompile
(CNPC::ShowTutorialHTML2 → CShowTutorialHTMLTimer) the third argument is the display delay
in seconds: the engine sets AddTimer(1000*nDelaySec) and on firing shows the window
with a sound played. namespace CNPC.
Signature
ShowTutorialHTML2( CSharedCreatureData c, string sFile, int nDelaySec, string sSound )Parameters
c (CSharedCreatureData) — the player who is shown the tutorial window.
sFile (string) — the tutorial .htm file name.
nDelaySec (int) — the delay before showing the window, seconds (engine: AddTimer(1000*nDelaySec); 3 in calls).
sSound (string) — the name of the sound played on display (e.g. "ItemSound.quest_tutorial").Example
ShowTutorialHTML2( talker, "tutorial_03.htm", 3, "ItemSound.quest_tutorial" );
ShowTutorialHTML2( talker, "tutorial_05.htm", 3, "ItemSound.quest_tutorial" );ShowNewTutorialHTMLNPC🟢 high
Shows the player cCreature a new-format tutorial window from the file sFile (localized .htm), namespace CNPC.
Signature
ShowNewTutorialHTML( CSharedCreatureData cCreature, string pwsName )Parameters
cCreature (CSharedCreatureData) — the player who is shown the new-format tutorial window
pwsName (string) — the name of the localized tutorial .htm fileExample
if (GetCountry(talker) == 2) { ShowNewTutorialHTML(talker, "..\L2text\pet_visual26-ua.htm"); }Usage example
if (GetCountry(talker) == 2) { ShowNewTutorialHTML(talker, "..\L2text\pet_visual26-ua.htm"); }
else if (GetCountry(talker) == 4) { ShowNewTutorialHTML(talker, "..\L2text\pet_visual26-cn.htm"); }
else if (GetCountry(talker) == 8) { ShowNewTutorialHTML(talker, "..\L2text\pet_visual26-ru.htm"); }
else { ShowNewTutorialHTML(talker, "..\L2text\pet_visual26-eu.htm"); }CloseTutorialHTMLNPC🟢 high
Closes the player cCreature's open tutorial window, namespace CNPC.
Signature
CloseTutorialHTML( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`cCreature`) whose tutorial window is closedExample
CloseTutorialHTML( talker );Usage example
else if ( reply == 999999) {
CloseTutorialHTML( talker );
return;
}EnableTutorialEventNPC🟢 high
Enables the player cCreature's tutorial events by a bit mask of flags, namespace CNPC.
The argument is a bit mask: scripts set/add individual bits (e.g. i0 | 1048576,
where 1048576 = 0x100000 — the bit of a specific class of tutorial events).
Signature
EnableTutorialEvent( CSharedCreatureData c, int nFlags )Parameters
c (CSharedCreatureData) — the player for whom tutorial events are enabled.
nFlags (int) — the bit mask of tutorial event flags (combined via OR;
in calls the bit 1048576 = 0x100000 is found).Example
EnableTutorialEvent( talker, ( i0 | 1048576 ) );Radar
3 functionsShowRadarNPC🟢 high
Places for the player cCreature a pointer marker at the point with coordinates nX, nY, nZ, namespace CNPC. The argument nType sets the radar: 1/2 or @RPT_BOTH (both radars at once).
Signature
ShowRadar( CSharedCreatureData c, int nX, int nY, int nZ, int nType )Parameters
c (CSharedCreatureData) — the player for whom the marker is placed.
nX (int) — the X coordinate of the marker point.
nY (int) — the Y coordinate of the marker point.
nZ (int) — the Z coordinate of the marker point.
nType (int) — the radar type (manual_pch): @RPT_RADAR (0) — radar only,
@RPT_MAP (1) — map only, @RPT_BOTH (2) — both.Example
ShowRadar( attacker, -2908, 44128, -2712, 1 );Usage example
if ( ( GetMemoStateEx( talker, @an_arrogant_search, 1 ) % 10 ) == 0 ) {
ShowRadar( talker, 181472, 7158, -2725, 1 );
}DeleteRadarNPC🟢 high
Removes for the player cCreature one marker at the point with coordinates nX, nY, nZ for the radar nType, namespace CNPC.
Signature
DeleteRadar( CSharedCreatureData c, int nX, int nY, int nZ, int nType )Parameters
c (CSharedCreatureData) — the player from whom the marker is removed.
nX (int) — the X coordinate of the removed marker.
nY (int) — the Y coordinate of the removed marker.
nZ (int) — the Z coordinate of the removed marker.
nType (int) — the radar type (manual_pch): @RPT_RADAR (0), @RPT_MAP (1), @RPT_BOTH (2).Example
DeleteRadar( talker, 10133, 157155, -2383, 2 );Usage example
if ( ( i0 % 10 ) == 0 ) {
DeleteRadar( attacker, -2908, 44128, -2712, 1 );
ShowRadar( attacker, -2908, 44128, -2712, 1 );
} else {
SetFlagJournal( attacker, @an_arrogant_search, 19 );
ShowQuestMark( attacker, @an_arrogant_search );
}DeleteAllRadarNPC🟢 high
Removes for the player cCreature all markers of the radar nType (@RPT_BOTH or 2), namespace CNPC.
Signature
DeleteAllRadar( CSharedCreatureData c, int nType )Parameters
c (CSharedCreatureData) — the player from whom all markers are removed.
nType (int) — the radar type (manual_pch): @RPT_RADAR (0), @RPT_MAP (1), @RPT_BOTH (2).Example
DeleteAllRadar(talker, @RPT_BOTH);
DeleteAllRadar( talker, 2 );Usage example
if ( reply == 65 ) {
DeleteAllRadar( talker, 2 );
ShowRadar( talker, 12311, 17470, -4574, 2 );
ShowPage( talker, "guide_delf_frankia_q0255_05.htm" );
}Henna
2 functionsOpenHennaItemListForEquipNPC🟢 high
Opens for the player cCreature the henna application (drawing) window, namespace CNPC.
Signature
OpenHennaItemListForEquip( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`cCreature`) for whom the henna application window is openedExample
OpenHennaItemListForEquip( talker );Usage example
if ( reply == 1 ) {
OpenHennaItemListForEquip( talker );
} else if ( reply == 2 ) {
OpenHennaListForUnquip( talker );
}OpenHennaListForUnquipNPC🟢 high
Opens for the player cCreature the henna removal window, namespace CNPC.
Signature
OpenHennaListForUnquip( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`cCreature`) for whom the henna removal window is openedExample
OpenHennaListForUnquip( talker );Usage example
if ( reply == 2 ) {
OpenHennaListForUnquip( talker );
}TRADE AND MANOR (Shop / Multisell / PC-Cafe / Manor)
27 functionsBuyNPC🟢 high
Opens the trade buy window for a player. Takes the buyer (talker), a goods list [CBuySellList] (e.g. BuyList0), three string html decoration pages (header, list, empty page) and the tax/markup as a fraction; all on the NPC (myself). Returns nothing.
Signature
Buy( CSharedCreatureData cCreature, CBuySellList pBuyList, string pwsPage0, string pwsPage1, string pwsEmptyPage, float dTax )Parameters
cCreature (CSharedCreatureData) — 1.
pBuyList (CBuySellList) — the list of goods for purchase displayed in the window
pwsPage0 (string) — html decoration page (window header)
pwsPage1 (string) — html decoration page (goods list)
pwsEmptyPage (string) — html page shown when the list is empty
dTax (float) — tax/markup fraction applied to the purchase priceExample
Buy( talker, BuyList0, ShopName, fnSell, fnUnableItemSell, -50 );SellNPC🟢 high
Opens the trade sell window for a player. Takes the seller (talker), a goods list [CBuySellList] (e.g. SellList0) and four string html window decoration pages; all on the NPC (myself). Returns nothing.
Signature
Sell( CSharedCreatureData cCreature, CBuySellList pSellList, string pwsPage0, string pwsPage1, string pwsPage2, string pwsEmptyPage )Parameters
cCreature (CSharedCreatureData) — the player for whom the sell window is opened
pSellList (CBuySellList) — the list of goods for sale displayed in the window
pwsPage0 (string) — html window decoration page
pwsPage1 (string) — html window decoration page
pwsPage2 (string) — html window decoration page
pwsEmptyPage (string) — html page shown when the list is emptyExample
Sell(talker, SellList0, ShopName, fnHi, _blank, _blank);ShowBuySellNPC🟢 high
Opens the combined buy-sell window — the more modern form of the trade window. Takes the player (talker), a buy goods list and a sell list (both [CBuySellList]) and a rate fraction; all on the NPC (myself). Returns nothing.
Signature
ShowBuySell( CSharedCreatureData pTalker, CBuySellList pBuyList, CBuySellList pSellList, float fRate )Parameters
pTalker (CSharedCreatureData) — the player for whom the buy-sell window is opened
pBuyList (CBuySellList) — the list of goods for purchase
pSellList (CBuySellList) — the list of goods for sale
fRate (float) — rate fraction (tax/markup) applied to pricesExample
ShowBuySell( talker, SellList0, BuyList0, -50 );Usage example
if ( GetPchValue( "client_hf" ) == 1 ) {
ShowBuySell( talker, SellList0, BuyList0, -50 );
} else {
Sell( talker, SellList0, ShopName, fnBuy, _blank, _blank );
}ShowMultisellNPC🟢 high
Opens a multisell for the player — an exchange by predefined recipes — with the given identifier. Takes the recipe identifier (a raw number from the multisell data, often the incoming menu item number) and the player (talker); called on the NPC (myself). Returns nothing.
Signature
ShowMultisell( int nMultisellId, CSharedCreatureData c )Parameters
nMultisellId (int) — multisell list/recipe identifier (raw number from the data, often a menu item number).
c (CSharedCreatureData) — the player for whom the multisell is opened (usually talker).Example
ShowMultisell(212, talker);Usage example
if ( GetSSQPart( talker ) != 0 ) {
ShowMultisell( reply, talker );
}GiveItemByPCCafePointNPC🟢 high
Gives the player an item for PC-Cafe points, deducting the specified cost. Per the L2NPC
decompile (CNPC::GiveItemByPCCafePoint_49224C) the engine checks the cost against the point
balance (will not give the item if insufficient), requires a non-negative item/enchant/count,
and sends the grant as an opcode 122 packet of format "cddddQ" (the enchant is a plain int,
the count is a 64-bit Q). ATTENTION: the order of the last two is enchant, then count (the
previous table had them swapped).
Returns 1 on success, 0 on insufficient points/error.
Signature
GiveItemByPCCafePoint( CSharedCreatureData c, int nCost, int nItemClassId, int nEnchant, int64 nCount )Parameters
c (CSharedCreatureData) — the player receiving the item for PC-Cafe points.
nCost (int) — cost in PC-Cafe points deducted for the grant (checked against the balance).
nItemClassId (int) — identifier of the item being given.
values — from the [item_pch] dictionary
nEnchant (int) — enchant level of the item being given (0 in the calls; must be >= 0).
nCount (int64) — count of the item being given (1 in the calls; must be >= 0).Example
GiveItemByPCCafePoint(talker, ticket_price, event_ticket, 0, 1);Usage example
if ( GetDailyQuestFlag( talker, 993 ) == 1 ) {
GiveItemByPCCafePoint( talker, ticket_price, event_ticket, 0, 1 );
SetDailyQuestFlag( talker, 993 );
} else {
ShowPage( talker, NotYetTime );
}GetPCCafePointNPC🟢 high
Reports how many PC-Cafe points the player has. Takes the player; called on the NPC (myself). Returns an integer — the point count, used as a gate before giving a reward.
Signature
GetPCCafePoint( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose PC-Cafe points are queriedExample
if (GetPCCafePoint(talker) >= ticket_price) {Usage example
if ( i9 > -1 && enter_type > -1 && ( GetPCCafePoint( talker ) >= required_PCCafePoint || pccafe_pass_mode == 2 ) ) {
if ( IsUserPremium( talker ) == @FALSE ) {
ShowPage( talker, "npc_rim_maker001e.htm" );
return;
}
InstantZone_Enter( talker, i9, enter_type );
}IsPCCafeUserNPC🟢 high
Checks whether the player is playing from a PC-Cafe. Takes the player; called on the NPC (myself). Returns an integer flag (1 — playing from a cafe), used together with the point check.
Signature
IsPCCafeUser( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose PC-Cafe play flag is checkedExample
if (IsPCCafeUser(target) == @TRUE)Usage example
if ( IsPCCafeUser( talker ) == 1 ) {
GiveItem1( talker, cratae_reward, 5 );
}CanUsePCCafePointNPC🟢 high
Checks whether the player can use PC-Cafe points. Takes the player; called on the NPC (myself). Returns an integer flag.
Signature
CanUsePCCafePoint( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose ability to spend PC-Cafe points is checked
Example (illustrative):
CanUsePCCafePoint( talker );UpdatePCCafePointNPC🟢 high
Changes the player's PC-Cafe point balance by the given amount (positive or negative). Takes the player and the change amount; called on the NPC (myself). Returns an integer.
Signature
UpdatePCCafePoint( CSharedCreatureData c, int nDelta )Parameters
c (CSharedCreatureData) — the player whose PC-Cafe point balance is changed.
nDelta (int) — signed point change amount (e.g. -1000 in the calls).Example
if ( UpdatePCCafePoint( talker, -1000 ) == 1 || pccafe_pass_mode == 2 ) {ShowManorDefaultInfoNPC🟢 high
Shows the player a general manor summary. Takes the player; called on the NPC (myself) — the castle manager. Returns nothing.
Signature
ShowManorDefaultInfo( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player who is shown the manor summaryUsage example
if ( ask == 5 ) { ShowManorDefaultInfo( talker ); } else
if ( ask == 7 ) { ShowSeedSetting( talker, state ); } else
if ( ask == 8 ) { ShowCropSetting( talker, state ); }ShowSeedInfoNPC🟢 high
Shows the player manor seed information. Takes the player, the manor identifier and the time; called on the NPC (myself). Returns nothing.
Signature
ShowSeedInfo( CSharedCreatureData pTalker, int nManorState, int nTime )Parameters
pTalker (CSharedCreatureData) — the player who is shown the seed information (talker).
nManorState (int) — manor identifier: the NPC's residence_id (state/manor_id in the scripts;
when state == -1, myself.sm.residence_id is substituted).
nTime (int) — manor period/time. Comes as the time field of the
MANOR_MENU_SELECTED(talker, …, time) event; not set directly by the script.Usage example
if ( state == -1 ) {
ShowSeedInfo( talker, manor_id, time );
} else {
ShowSeedInfo( talker, state, time );
}ShowCropInfoNPC🟢 high
Shows the player manor crop information. Takes the player, the manor identifier and the time; called on the NPC (myself). Returns nothing.
Signature
ShowCropInfo( CSharedCreatureData pTalker, int nManorState, int nTime )Parameters
pTalker (CSharedCreatureData) — the player who is shown the crop information (talker).
nManorState (int) — manor identifier: the NPC's residence_id (state/manor_id in the scripts;
when state == -1, myself.sm.residence_id is substituted).
nTime (int) — manor period/time. Comes as the time field of the
MANOR_MENU_SELECTED(talker, …, time) event; not set directly by the script.Usage example
if ( state == -1 ) {
ShowCropInfo( talker, manor_id, time );
} else {
ShowCropInfo( talker, state, time );
}ShowSeedSettingNPC🟢 high
Shows the lord the seed sale settings menu. Takes the player and the state; called on the NPC (myself). Returns nothing.
Signature
ShowSeedSetting( CSharedCreatureData cCreature, int nManorState )Parameters
cCreature (CSharedCreatureData) — the lord who is shown the seed sale settings menu
nManorState (int) — menu state/mode (manor state/id in the calls)Example
ShowSeedSetting(talker, state);Usage example
if ( ask == 7 ) {
ShowSeedSetting( talker, state );
} else
if ( ask == 8 ) {
ShowCropSetting( talker, state );
}ShowCropSettingNPC🟢 high
Shows the lord the crop procurement settings menu. Takes the player and the state; called on the NPC (myself). Returns nothing.
Signature
ShowCropSetting( CSharedCreatureData cCreature, int nManorState )Parameters
cCreature (CSharedCreatureData) — the lord who is shown the crop procurement settings menu
nManorState (int) — menu state/mode (manor state/id in the calls)Usage example
if ( ask == 8 ) {
ShowCropSetting( talker, state );
}ShowProcureCropListNPC🟢 high
Shows the player the list of crops the castle procures. Takes the player and the manor identifier; called on the NPC (myself). Returns nothing.
Signature
ShowProcureCropList( CSharedCreatureData cCreature, int nManorId )Parameters
cCreature (CSharedCreatureData) — the player who is shown the list of procured crops
nManorId (int) — manor identifierExample
ShowProcureCropList(talker, manor_id);ShowProcureCropDetailNPC🟢 high
Shows the player the details of a single procured crop entry. Takes the player and the state; called on the NPC (myself). Returns nothing.
Signature
ShowProcureCropDetail( CSharedCreatureData cCreature, int nManorState )Parameters
cCreature (CSharedCreatureData) — the player who is shown the crop entry details
nManorState (int) — state/selected entry (manor state in the calls)Usage example
if ( ask == 9 ) {
ShowProcureCropDetail( talker, state );
}ShowSellSeedListNPC🟢 high
Shows the player the list of seeds for sale. Takes the player and the manor identifier; called on the NPC (myself). Returns nothing.
Signature
ShowSellSeedList( CSharedCreatureData cCreature, int nManorId )Parameters
cCreature (CSharedCreatureData) — the player who is shown the list of seeds for sale
nManorId (int) — manor identifierExample
ShowSellSeedList(talker, manor_id);Manor_GetSeedIncomeNPC🟢 high
Reports the manor's accumulated income from seed sales. No arguments; works with the manor
of the NPC's own residence. Returns a 64-bit number (the adena amount from the manor data),
so there is no overflow.
Signature
Manor_GetSeedIncome( )Parameters
(none — the function is called without arguments)Example
FHTML_SetInt(fhtml0, "seed_income", Manor_GetSeedIncome());GetSeedClassidByOrderNumNPC🟢 high
Given the selected castle and a seed's position number in its list, returns the class_id of the seed item itself. Each castle's seed list is split into positions (1, 2, 3, …), and the seeds occupying them have different class_ids — this function translates the "row number in the dialog" into the real class_id, to show the player the seed's name or verify that exactly this seed is being bought. Fully analogous to GetCropClassidByOrderNum, only for seeds rather than crops.
The first argument is the castle (manor) id: the lord/player first picks a castle from the menu, its number is stored in the "ManorId" cookie and passed here. The second argument is the seed number chosen in the list (reply). Returns the seed's class_id (0 if the position is empty/invalid).
Signature
GetSeedClassidByOrderNum( int nManorId, int nOrderNum )Parameters
nManorId (int) — id of the castle/manor the seed list belongs to (usually from the "ManorId" cookie).
nOrderNum (int) — the seed's position number in the castle's list; in the dialog this is the player's choice (`reply`).Example
i1 = GetSeedClassidByOrderNum( i0, reply );GetCropClassidByOrderNumNPC🟢 high
Given the selected castle and a crop's position number in its list, returns the class_id of the crop item itself. Each castle's crop list is fixed by positions (1, 2, 3, …), while items with different class_ids can be planted and turned in — this function translates the "row number in the dialog" into the real class_id, to then show the player the crop's name or verify that he is turning in exactly that item.
The first argument is the castle (manor) id: in the dialog the lord first picks a castle from the menu, the castle number is stored in the "ManorId" cookie and then passed here. The second argument is the crop number the player chose in the list (reply). Returns the crop's class_id (0 if the position is empty/invalid).
Signature
GetCropClassidByOrderNum( int nManorId, int nOrderNum )Parameters
nManorId (int) — id of the castle/manor the crop list belongs to (usually taken from the "ManorId" cookie).
nOrderNum (int) — the crop's position number in the castle's list; in the dialog this is the player's choice (`reply`).Example
i1 = GetCropClassidByOrderNum(i0, reply);GetCurrentSeedPriceNPC🟢 high
Given the selected castle and a seed's number in its list, returns the price at which the castle currently sells this seed to players. This is the effective price of the current period: it has already been set by the lord and trading proceeds at it until the settings change next. The value is inserted into an HTML dialog field (e.g. "CurrentSeedPrice") so that the player or lord sees the current price.
The first argument is the castle (manor) id; in the dialog it comes from the castle selection in the menu (variables state / i0, the number is in the "ManorId" cookie). The second argument is the seed number: either the player's specific choice (reply) or the index i2 when iterating over all 25 positions to fill the table. Returns the price in adena.
Signature
GetCurrentSeedPrice( int nManorId, int nOrderNum )Parameters
nManorId (int) — id of the castle/manor whose seed price list we read (state / i0 in the scripts, from the castle selection menu).
nOrderNum (int) — the seed's position number in the list; the player's choice (`reply`) or the iteration index i2 (1..25).Example
FHTML_SetInt( fhtml0, "CurrentSeedPrice" + i2, GetCurrentSeedPrice( state, i2 ) );GetCurrentSeedSellCountSetNPC🟢 high
Given the selected castle and a seed number, returns the sale limit set by the lord for the current period: how many units of this seed in total the castle is willing to sell to players during the period. This is the planned number from the manufacture settings, not the stock remainder (the remainder is returned by GetCurrentSeedRemainCount). The value is shown in the dialog field "CurrentSeedCount".
The first argument is the castle (manor) id; in the dialog it comes from the castle selection (state / i0). The second argument is the seed number: the index i2 when iterating over all 25 positions for the table, or the player's choice (reply).
Signature
GetCurrentSeedSellCountSet( int nManorId, int nOrderNum )Parameters
nManorId (int) — id of the castle/manor whose seed sale plan we read (state / i0 in the scripts, from the castle selection menu).
nOrderNum (int) — the seed's position number in the list; the iteration index i2 (1..25) or the player's choice (`reply`).Example
FHTML_SetInt( fhtml0, "CurrentSeedCount" + i2, GetCurrentSeedSellCountSet( state, i2 ) );GetCropDefaultPriceNPC🟢 high
Given the selected castle and a crop number, returns the base (starting) price of the crop — the reference value from which procurement is calculated. This is not the current price declared by the lord, but the position's base rate: it is convenient for showing the "recommended" price and calculating the planned revenue. It pairs with GetSeedDefaultPrice, which likewise returns the base price for a seed; in the dialog that one is called as GetSeedDefaultPrice( i0, i2 ) — the same two arguments.
The first argument is the castle (manor) id; in the dialog it comes from the castle selection (variables state / i0, the number is in the "ManorId" cookie). The second argument is the crop number: the index i2 when iterating over all 25 positions, or the player's choice (reply). Returns the price in adena.
Signature
GetCropDefaultPrice( int nManorId, int nOrderNum )Parameters
nManorId (int) — id of the castle/manor whose base crop price we read (state / i0 in the scripts, from the castle selection menu).
nOrderNum (int) — the crop's position number in the list; the iteration index i2 (1..25) or the player's choice (`reply`).
Example (illustrative; there are no direct calls in the collected scripts, but the paired GetSeedDefaultPrice is called exactly the same way):
i1 = GetCropDefaultPrice( i0, i2 );GetRemainProcureCropCountNPC🟢 high
Given the selected castle and a crop number, returns how much of this crop the castle is still willing to accept from players before the period ends. The castle declares a procurement plan for the period; players turn in the crop, and this number decreases. When it reaches zero, the castle no longer buys this kind of crop. The value is shown in the dialog field "RemainCropCount" so the player can see whether it is still worth bringing the crop for turn-in.
The first argument is the castle (manor) id; in the dialog it comes from the castle selection (variables manor_id / state / i0). The second argument is the crop number: the index i2 when iterating over all 25 positions for the table, or the player's choice (reply).
Signature
GetRemainProcureCropCount( int nManorId, int nOrderNum )Parameters
nManorId (int) — id of the castle/manor whose procurement remainder we read (manor_id / state / i0 in the scripts, from the castle selection menu).
nOrderNum (int) — the crop's position number in the list; the iteration index i2 (1..25) or the player's choice (`reply`).Example
FHTML_SetInt( fhtml0, "RemainCropCount" + i2, GetRemainProcureCropCount( manor_id, i2 ) );SetSeedSellPropertyNPC🟢 high
Setter for the seed getters (GetCurrentSeedPrice / GetCurrentSeedSellCountSet): the lord sets, for a single seed position, at what price and in what quantity the castle will sell this seed to players in the next period. These values then fill the "NextSeedPrice"/"NextSeedCount" fields in the dialog, and when the new period starts they become the current ones.
The first argument is the lord himself who changes the setting (his manor rights are checked through him). Then — which castle and which position we are editing, then the new price and the new limit. The castle identifier must be a real castle number (you cannot pass the "menu state" instead, otherwise the setting will not apply).
Signature
SetSeedSellProperty( CSharedCreatureData cCreature, int nManorId, int nOrderNum, int64 nPrice, int64 nCount )Parameters
cCreature (CSharedCreatureData) — the lord (or authorized clan member) setting the property; his manor rights are verified.
nManorId (int) — id of the castle/manor whose seed we configure (a real castle number, not a "menu state").
nOrderNum (int) — the seed's position number in the castle's list (the same index as in the seed getters).
nPrice (int64) — new seed sale price to players (adena per unit).
nCount (int64) — new sale limit: how many units of this seed the castle will offer for the period.
Example (illustrative; there are no direct calls in the collected scripts, the argument order is taken from the signature and confirmed by the paired getters):
SetSeedSellProperty( talker, i0, reply, i_price, i_count );SetCropProcurePropertyNPC🟢 high
Setter for the crop getters (GetProcurementRate / GetProcurementCount / GetProcurementType and GetRemainProcureCropCount): the lord sets, for a single crop position, at what price and in what volume the castle will buy this crop from players in the next period. These values are then visible in the dialog as "NextProcurePrice"/"NextProcureCount"/"NextProcureType", and when the new period starts they determine how much crop the castle will accept.
The first argument is the lord himself (his manor rights are checked through him). Then — which castle and which crop position we are editing, then the procurement price, a separate "procurement type" parameter and the volume. The crop's separate parameter (nArg) corresponds to the "procurement type" that GetProcurementType returns on read (e.g. payment form/acceptance mode); the difference from seeds is that crops have this setting while seeds do not — hence the extra int in the signature between the price and the count.
The argument order is "price (64-bit) → type → count (64-bit)"; the manor id is accepted in the range 1..40. There are no direct calls in the collected scripts, but the layout and the presence of a separate "procurement type" between the price and the volume are confirmed and consistent with the paired seed setter SetSeedSellProperty (seeds have no "type").
Signature
SetCropProcureProperty( CSharedCreatureData cCreature, int nManorId, int nOrderNum, int64 nPrice, int nArg, int64 nCount )Parameters
cCreature (CSharedCreatureData) — the lord (or authorized clan member) setting the property; his manor rights are verified.
nManorId (int) — id of the castle/manor whose crop procurement we configure (a real castle number).
nOrderNum (int) — the crop's position number in the castle's list (the same index as in the procurement getters).
nPrice (int64) — crop procurement price (adena per unit) the castle will offer to players.
nArg (int) — procurement type/mode for this position (a value with the same meaning as GetProcurementType returns).
nCount (int64) — procurement volume: how many units of this crop the castle is willing to accept for the period.
Example (illustrative — there are no direct calls in the collected scripts):
SetCropProcureProperty( talker, i0, reply, i_price, i_type, i_count );GiveItemByCastleSiegeDefenceNPC🟢 high
Exchanges the clan's accumulated "castle defence counter" for a reward: deducts nConsume
units of this counter from the player's clan and gives the player an item. Requires the
player to be the clan leader and his clan's defence counter to be at least nConsume;
otherwise nothing is given. The counter accumulates for the clan's participation in castle
defence during sieges and is read via GetPledgeCastleSiegeDefenceCount.
Signature
GiveItemByCastleSiegeDefence( CSharedCreatureData cCreature, int nConsume, int nItemClassId, int nEnchant, int64 nCount )Parameters
cCreature (CSharedCreatureData) — the player (clan leader) receiving the reward; his clan
must have a defence counter >= nConsume.
nConsume (int) — how many units of the "castle defence counter" to deduct from the clan (in the
example — the whole accumulated counter i0).
nItemClassId (int) — class of the item being given (defence medal); values from the [item_pch] dictionary.
nEnchant (int) — enchant/extra field of the item being given (0 in the example).
nCount (int64) — count of the item being given (i0 in the example — one medal per
counter unit).Example
GiveItemByCastleSiegeDefence(talker, i0, item_medal, 0, i0);Usage example
i0 = GetPledgeCastleSiegeDefenceCount( talker );
if ( i0 == 0 ) {
ShowPage( talker, fnNoReward );
return;
}
GiveItemByCastleSiegeDefence( talker, i0, item_medal, 0, i0 );Manor: seeds & crops (Manor / Seeds)
13 functionsGetProcurementCountNPC🟢 high
Getter of the agrarian manor system (CNPC). Returns int — the amount of crop procured by the residence in the current cycle for seed type nSeedType at state nManorState. The value is inserted into the manor manager's HTML menu.
Signature
GetProcurementCount( int nManorState, int nSeedType )Parameters
nManorState (int) — manor state/period. In real calls = 1 (the manor_id/state variables
are initialized to one); there are no dedicated @-constants for it.
nSeedType (int) — crop type = ordinal index 1..25, iterated by the loop for i2=1..25
when building the manor's HTML menu.Example
FHTML_SetInt( fhtml0, "CurrentCropProcureCount" + i2, GetProcurementCount( manor_id, i2 ) );GetProcurementRateNPC🟢 high
Manor getter (CNPC). Given state nManorState and seed type nSeedType, returns int — the crop procurement price (rate) for the current cycle. Used to render current prices in the menu.
Signature
GetProcurementRate( int nManorState, int nSeedType )Parameters
nManorState (int) — manor state/period. In real calls = 1 (the manor_id/state variables
are initialized to one); there are no dedicated @-constants for it.
nSeedType (int) — crop type = ordinal index 1..25, iterated by the loop for i2=1..25
when building the manor's HTML menu.Example
FHTML_SetInt( fhtml0, "CurrentCropPrice" + i2, GetProcurementRate( manor_id, i2 ) );GetProcurementTypeNPC🟢 high
Manor getter (CNPC). Given nManorState and nSeedType, returns int — the crop procurement type (flag) of the current cycle. Goes into the HTML menu next to the count and price.
Signature
GetProcurementType( int nManorState, int nSeedType )Parameters
nManorState (int) — manor state/period. In real calls = 1 (the manor_id/state variables
are initialized to one); there are no dedicated @-constants for it.
nSeedType (int) — crop type = ordinal index 1..25, iterated by the loop for i2=1..25
when building the manor's HTML menu.Example
FHTML_SetInt( fhtml0, "CurrentProcureType" + i2, GetProcurementType( manor_id, i2 ) );GetNextProcurementCountNPC🟢 high
Manor getter (CNPC). Given state nManorState and seed type nSeedType, returns int — the crop procurement volume planned for the next cycle.
Signature
GetNextProcurementCount( int nManorState, int nSeedType )Parameters
nManorState (int) — manor state/period. In real calls = 1 (the manor_id/state variables
are initialized to one); there are no dedicated @-constants for it.
nSeedType (int) — crop type = ordinal index 1..25, iterated by the loop for i2=1..25
when building the manor's HTML menu.Example
FHTML_SetInt( fhtml0, "NextProcureCount" + i2, GetNextProcurementCount( state, i2 ) );GetNextSeedPriceNPC🟢 high
Manor getter (CNPC). Given state nManorState and seed type nSeedType, returns int — the seed sale price set for the next period.
Signature
GetNextSeedPrice( int nManorState, int nSeedType )Parameters
nManorState (int) — manor identifier: the NPC's residence_id (in scripts the variables manor_id/state/i0,
usually = 1; when state == -1, myself.sm.residence_id is substituted).
nSeedType (int) — crop type = ordinal index 1..25 (iterated by the loop for i2=1..25).Example
FHTML_SetInt( fhtml0, "NextSeedPrice" + i2, GetNextSeedPrice( state, i2 ) );GetSeedDefaultPriceNPC🟢 high
Manor getter (CNPC). Given nManorState and nSeedType, returns int — the base (default) seed price from which sale settings are computed.
Signature
GetSeedDefaultPrice( int nManorState, int nSeedType )Parameters
nManorState (int) — manor identifier: the NPC's residence_id (in scripts the variables manor_id/state/i0,
usually = 1; when state == -1, myself.sm.residence_id is substituted).
nSeedType (int) — crop type = ordinal index 1..25 (iterated by the loop for i2=1..25).Example
FHTML_SetInt( fhtml0, "DefaultSeedPrice" + i2, GetSeedDefaultPrice( i0, i2 ) );GetNextSeedSellCountSetNPC🟢 high
For the selected castle and seed number, returns the sale limit set for the NEXT period: how many units of this seed the castle will put up for sale when the new manufacture cycle begins. This is the counterpart of GetCurrentSeedSellCountSet (which returns the current period's limit) — in the settings dialog they are shown side by side ("now" and "will become") so the lord can see what he changed. The value is inserted into the "NextSeedCount" field.
The first argument is the castle (manor) id; in the dialog it comes from the castle selection (state / i0). The second argument is the seed number: the index i2 when iterating all 25 positions for the table, or the player's choice (reply).
Signature
GetNextSeedSellCountSet( int nManorId, int nOrderNum )Parameters
nManorId (int) — id of the castle/manor whose next-period plan is being read (in scripts state / i0, from the castle selection menu).
nOrderNum (int) — number of the seed position in the list; the iteration index i2 (1..25) or the player's choice (`reply`).Example
FHTML_SetInt( fhtml0, "NextSeedCount" + i2, GetNextSeedSellCountSet( state, i2 ) );GetCurrentSeedRemainCountNPC🟢 high
Manor getter (CNPC). Given state nManorState and seed type nSeedType, returns int — the unsold remainder of seeds for the current period.
Signature
GetCurrentSeedRemainCount( int nManorState, int nSeedType )Parameters
nManorState (int) — manor identifier: the NPC's residence_id (in scripts the variables manor_id/state/i0,
usually = 1; when state == -1, myself.sm.residence_id is substituted).
nSeedType (int) — crop type = ordinal index 1..25 (iterated by the loop for i2=1..25).Example
FHTML_SetInt( fhtml0, "CurrentSeedRemain" + i2, GetCurrentSeedRemainCount( state, i2 ) );GetMaxSellableCountNPC🟢 high
Manor getter (CNPC). Given nManorState and nSeedType, returns int — the maximum allowed number of seeds for sale.
Signature
GetMaxSellableCount( int nManorState, int nSeedType )Parameters
nManorState (int) — manor identifier: the NPC's residence_id (in scripts the variables manor_id/state/i0,
usually = 1; when state == -1, myself.sm.residence_id is substituted).
nSeedType (int) — crop type = ordinal index 1..25 (iterated by the loop for i2=1..25).Example
FHTML_SetInt( fhtml0, "MaxSell" + i2, GetMaxSellableCount( i0, i2 ) );IsManorSettingTimeNPC🟢 high
Manor predicate (CNPC), no arguments. Returns 1 if the manor setup period (prices/plans)
is currently active, otherwise 0. Per the decompile, the setup window is the time of day outside
the 8..19 hour range (i.e. from 20:00 to 07:59). The menu uses it to decide whether to allow
editing parameters.
Signature
IsManorSettingTime( )Parameters
(none — the function is called without arguments)Example
if ( IsManorSettingTime( ) == 1 ) {Usage example
if ( IsManorSettingTime( ) == 0 ) {
FHTML_SetFileName( fhtml0, "manor_crop_client_info_next.htm" );
}SellPreviewNPC🟢 high
Method of the manor/trade menu (CNPC). Shows creature c a preview of the sale list: arguments — a list of goods (CBuySellList) and three page-layout strings (sPage0..sPage2).
Signature
SellPreview( CSharedCreatureData cCreature, CBuySellList pSellList, string pwsPage0, string pwsPage1, string pwsPage2, string pwsEmptyPage )Parameters
cCreature (CSharedCreatureData) — creature (player) shown the sale preview
pSellList (CBuySellList) — list of goods put up for sale
pwsPage0 (string) — first layout string of the menu page
pwsPage1 (string) — second layout string of the menu page
pwsPage2 (string) — third layout string of the menu page
pwsEmptyPage (string) — text shown when the sale list is emptyExample
SellPreview( talker, SellList0, ShopName, fnBuy, _blank, _blank );Usage example
if ( reply == 2 ) {
SellPreview( talker, SellPreview1, ShopName, fnBuy, _blank, _blank );
}GetNextProcurementRateNPC🟢 high
Returns the purchase price of the manor's next good. Takes the state (state) and
the position number; called on myself and usually substituted into an HTML field.
Works in pair with GetNextProcurementType.
Signature
GetNextProcurementRate( int nManorState, int nSeedType )Parameters
nManorState (int) — the manor state/period. In real calls = 1 (the manor_id/state variables
are initialized to one); there are no separate @-constants for it.
nSeedType (int) — the crop type = the ordinal index 1..25, iterated by the loop for i2=1..25
when building the manor HTML menu.Example
FHTML_SetInt( fhtml0, "NextProcurePrice" + i2, GetNextProcurementRate( state, i2 ) );GetNextProcurementTypeNPC🟢 high
Returns the type of the manor's purchased good (seeds/crop). Takes the state
(state) and the position number; called on myself. Works in pair with
GetNextProcurementRate, usually for output into HTML.
Signature
GetNextProcurementType( int nManorState, int nSeedType )Parameters
nManorState (int) — the manor state/period. In real calls = 1 (the manor_id/state variables
are initialized to one); there are no separate @-constants for it.
nSeedType (int) — the crop type = the ordinal index 1..25, iterated by the loop for i2=1..25
when building the manor HTML menu.Example
FHTML_SetInt( fhtml0, "NextProcureType" + i2, GetNextProcurementType( state, i2 ) );Marriage
2 functionsMarryNPC🟢 high
Registers a marriage between two characters by their indexes. Takes two indexes
(idx1, idx2), usually obtained via GetIndexFromCreature; returns nothing.
Signature
Marry( int nChar1Index, int nChar2Index )Parameters
nChar1Index (int) — the index of the first character entering the marriage
nChar2Index (int) — the index of the second character entering the marriageExample
Marry( GetIndexFromCreature(myself.c_ai0), GetIndexFromCreature(myself.c_ai1) );DivorceNPC🟢 high
Dissolves a marriage: removes the marriage status for a player. Takes the player index
(user_idx), usually obtained via GetIndexFromCreature; returns nothing.
Signature
Divorce( int nCharIndex )Parameters
nCharIndex (int) — the index of the player whose marriage is dissolvedExample
Divorce( GetIndexFromCreature( talker ) );Usage example
if ( myself.i_ai0 == 0 ) {
Divorce( GetIndexFromCreature( talker ) );
ShowPage( talker, "sia_wedding012a.htm" );
}UTILITIES — STRINGS, NUMBERS, CHECKS (Utility)
12 functionsRandGLOBAL🟢 high
Returns a random integer in the range from zero to the value of [base] minus one.
Takes a single argument [base] (the upper bound, exclusive), namespace not
set. All probabilistic logic rests on this function — drop and line chances,
enchant spread, random branching.
Signature
Rand( int base )Parameters
base (int) — the upper bound (exclusive).Example
i0 = Rand( 4 );Usage example
if ( MoveAroundSocial1 > 0 && Rand( 100 ) < 40 ) {
AddEffectActionDesire( myself.sm, 2, ( ( MoveAroundSocial1 * 1000 ) / 30 ), 50 );
}MakeFStringGLOBAL🟢 high
Builds a string from a localized NPC-string with identifier [id], substituting up to
five parameters [p1]..[p5]. Arguments: [id] (a client string id) and five string
substitutions, namespace not set; returns the ready text, which is usually passed to
Say, Shout, or FHTML. Unused parameters are left empty (_blank or
an empty string), and calls can be nested inside one another.
Where the id comes from: the strings themselves lie in the chronicle's fstring.txt file — by the id from
the call the text is found there (for example, 1001000 = "The Kingdom of Aden",
1001100 = "The Kingdom of Elmore"; hence the idiom MakeFString(1001000 +
myself.sm.residence_id, ...) — the domain name by residence number).
Signature
MakeFString( int id, string pwsValue1, string pwsValue2, string pwsValue3, string pwsValue4, string pwsValue5 )Parameters
id (int) — a client string id.
pwsValue1 (string) — the first string substitution into the template (in place of [p1]); empty — `_blank`
pwsValue2 (string) — the second string substitution (in place of [p2]); empty — `_blank`
pwsValue3 (string) — the third string substitution (in place of [p3]); empty — `_blank`
pwsValue4 (string) — the fourth string substitution (in place of [p4]); empty — `_blank`
pwsValue5 (string) — the fifth string substitution (in place of [p5]); empty — `_blank`Example
Say( MakeFString( 33413, "", "", "", "", "" ) );MakeFStringMultiGLOBAL🟢 high
Works like MakeFString, but additionally takes a creature [c] — apparently,
for multilingual substitution according to a specific player's language or locale. Arguments: [c]
(for whom the string is built), [id] (the string id) and five string substitutions
[p1]..[p5], namespace not set; returns the assembled string. No direct calls were
extracted from the code.
Signature
MakeFStringMulti( CSharedCreatureData c, int id, string pwsValue1, string pwsValue2, string pwsValue3, string pwsValue4, string pwsValue5 )Parameters
c (CSharedCreatureData) — for whom the string is built (language/context).
id (int) — the string id.
pwsValue1 (string) — the first string substitution into the template (in place of [p1]); empty — `_blank`
pwsValue2 (string) — the second string substitution (in place of [p2]); empty — `_blank`
pwsValue3 (string) — the third string substitution (in place of [p3]); empty — `_blank`
pwsValue4 (string) — the fourth string substitution (in place of [p4]); empty — `_blank`
pwsValue5 (string) — the fifth string substitution (in place of [p5]); empty — `_blank`
Example (illustrative):
MakeFStringMulti( talker, id, "", "", "", "", "" );IntToStrGLOBAL🟢 high
Converts an integer to text for insertion into lines and HTML windows. Takes a
single argument [nValue] (the source number), namespace not set; returns the
string representation.
Signature
IntToStr( int nValue )Parameters
nValue (int) — the integer to turn into textExample
FHTML_SetStr( fhtml0, "p_member_count0", IntToStr( i1 ) );StrToIntGLOBAL🟢 high
Parses text back into an integer — used when parsing string
parameters. Takes a single argument [sValue] (the source string), namespace not
set; returns an integer.
Signature
StrToInt( string sValue )Parameters
sValue (string) — the source string parsed into an integerExample
i2 = StrToInt( s0 );Usage example
if ( StrToInt( s0 ) == 2 ) {
FHTML_SetStr( fhtml0, "Winner", MakeFString( 1000311, "", "", "", "", "" ) );
} else {
FHTML_SetStr( fhtml0, "Winner", "" );
}FloatToIntGLOBAL🟢 high
Converts a fractional number to an integer (truncation or rounding). Takes a single
argument [fValue] (the source fractional value), namespace not set; returns an integer
number. Especially often needed for coordinates: a creature's position is stored as fractional, while
the spawn and teleport functions expect integers.
Signature
FloatToInt( float fValue )Parameters
fValue (float) — the source fractional value truncated/rounded to an integerExample
x = FloatToInt(speller.x);Usage example
if ( FloatToInt( ( ( attacker.hp / attacker.max_hp ) * 100 ) ) < 20 && Rand( 100 ) < 3 && attacker.is_pc == 1 ) {
CreateOnePrivateEx( HelpHeroSilhouette, HelpHeroAI, 0, 0, ( FloatToInt( myself.sm.x ) + 80 ), ( FloatToInt( myself.sm.y ) + 80 ), FloatToInt( myself.sm.z ), 0, 0, 0, GetIndexFromCreature( myself.sm ) );
}GetIndexFromCreatureGLOBAL🟢 high
Returns the numeric index or object identifier of the creature [c]. Takes a
single argument [c] (a creature), namespace not set; returns an int. Needed where
a function takes not a creature but the int-id of a target or owner — for example, a spawn's
owner or a skill target given by number.
Signature
GetIndexFromCreature( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature.Example
i0 = GetIndexFromCreature( last_attacker );IsNullGLOBAL🟢 high
Checks an arbitrary object for "empty/invalid". Takes a single
argument [o] (an object), namespace not set; returns one if the object is empty or
invalid, otherwise zero. Mandatory before accessing an object's fields, so as not to hit
an error on a missing value.
Signature
IsNull( object obj )Parameters
obj (object) — an arbitrary object checked for empty/invalidExample
if (IsNull(item0) == 0) {Usage example
while ( IsNull( code_info = always_list.Next( ) ) == 0 ) {
}IsNullCreatureNPC🟢 high
A typed check of a creature for "null/invalid", belongs to the NPC itself.
Takes a single argument [c] (creature), no namespace specified; returns
one if the creature is null or invalid, zero otherwise. Used before accessing
the target's fields.
Signature
IsNullCreature( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature checked for null/invalidExample
if (IsNullCreature(c0) == 0) {Usage example
if ( IsNullCreature( myself.boss ) == 0 && DistFromMe( myself.boss ) > 500 && myself.boss.alive != 0 && myself.p_state != 3 ) {
InstantTeleport( myself.sm, FloatToInt( myself.boss.x ), FloatToInt( myself.boss.y ), FloatToInt( myself.boss.z ) );
}IsNullPartyNPC🟢 high
A typed check of a party for "null/invalid". Takes a single
argument [p] (party), no namespace specified; returns one if the party is null
or invalid, zero otherwise.
Signature
IsNullParty( CSharedPartyData p )Parameters
p (CSharedPartyData) — the party checked for null/invalid.Example
if (IsNullParty(party0) == @FALSE)Usage example
if ( IsNullParty( party0 ) == 0 ) {
myself.i_ai0 = party0.id;
}IsNullStringNPC🟢 high
A typed check of a string for "null/invalid". Takes a single
argument [s] (string), no namespace specified; returns one if the string is empty or
invalid, zero otherwise.
Signature
IsNullString( string s )Parameters
s (string) — the string checked for null/invalid.Example
if (IsNullString(s0) == @TRUE) {Usage example
if ( IsNullString( DoorName ) == 0 ) {
Castle_GateOpenClose2( DoorName, 0 );
}IsNullHateInfoNPC🟢 high
A typed check of an aggro information record (hate-info) for "null/invalid".
Takes a single argument [h] (hate-info), no namespace specified; returns
one if the value is null or invalid, zero otherwise.
Signature
IsNullHateInfo( CHateInfo h )Parameters
h (CHateInfo) — the aggro information record (hate-info) checked for null/invalid.Example
if (IsNullHateInfo(h0) == @FALSE)Usage example
if (IsNullHateInfo(h0) == @TRUE || h0.hate <= 0)
{
h0 = GetMaxHateInfo(0);
}TIME AND CALENDAR (Time / DateTime)
5 functionsGetTimeOfDayGLOBAL🟢 high
This is NOT the "part of the day" as one might think from the name. The function takes the server's system
time and returns it as the number of seconds elapsed since January 1, 1970
(a Unix timestamp). No arguments, called on gg. Needed for arithmetic with
deadlines: the difference from a boundary mark gives "how many seconds remain". The classic
idiom — GetTimeOfSSQ(1) - GetTimeOfDay() — how many seconds until the end of the Seven
Signs period. Day or night is NOT determined by this function — for that there isGetL2Time(@L2F_IS_NIGHT) (see below) or GetTimeHour. The same timestamp is
fed to GetDateTime to parse "now" into year/month/hour, etc.
Signature
GetTimeOfDay( )Parameters
(none — the function is called without arguments)Example
i0 = GetTimeOfDay( );
i6 = GetTimeOfDay( );Usage example
if ( ( ( ( i0 >= 0 && i0 < 18 ) || ( i0 >= 20 && i0 < 38 ) ) || ( i0 >= 40 && i0 < 58 ) ) || ( GetTimeOfSSQ( 1 ) - GetTimeOfDay( ) ) <= 120 ) {
ShowPage( talker, "ssq_main_event_acolyte_q0505_22.htm" );
RemoveMemo( talker, @blood_offering );
return;
}GetDateTimeGLOBAL🟢 high
Parses a date-time into a single component and returns it as a number. The first
argument is a timestamp: zero means "now", nonzero means a specific moment,
for example the expiration date of a castle decoration. The second argument selects the component
(year, month, day, hour, minute, second, or day of week). Called on the global
object gg; for the day of week it returns a number from zero (Sunday) to six (Saturday).
Signature
GetDateTime( int nTime, int nField )Parameters
nTime (int) — the timestamp: 0 = current time; >0 = a specific moment (e.g. an expiration date).
nField (int) — which component to extract (confirmed by engine decompile):
0 year · 1 month · 2 day · 3 hour · 4 minute · 5 second · 6 day of week (0=Sun … 6=Sat)Example
i0 = GetDateTime( 0, 3 );Usage example
i0 = GetDateTime( 0, 4 );
if ( i0 > 49 && i0 < 60 ) {
Say( MakeFString( 1010552, "", "", "", "", "" ) );
return;
}GetL2TimeGLOBAL🟢 high
Returns a component of L2 in-game time (an in-game day runs faster than a
real one). Called on gg. The single argument is not "day/night", but the NUMBER
OF THE FIELD to get; the codes are taken from [manual_pch] (the same in all
chronicles):
@L2F_HOUR = 0 — the in-game hour
@L2F_MIN = 1 — the in-game minute
@L2F_IS_NIGHT = 2 — whether it is night now: 1 = night, 0 = day
That is, GetL2Time(@L2F_IS_NIGHT) is the most convenient way to check "is it night now?":
it returns 1 at night and 0 during the day. GetL2Time(@L2F_HOUR) is the same as GetTimeHour().
Not to be confused with GetTimeOfDay (which returns the raw server timestamp in seconds).
Signature
GetL2Time( int nField )Parameters
nField (int) — which time field to return: @L2F_HOUR(0) / @L2F_MIN(1) / @L2F_IS_NIGHT(2)Example
i1 = GetL2Time(@L2F_MIN);Usage example
i0 = GetL2Time(@L2F_IS_NIGHT);
if (i0 == 0) //Day
{
Despawn();
}GetLifeTimeNPC🟢 high
Returns how many seconds the NPC has lived since appearing. No arguments,
called on myself. The most frequent use — a "grace period" after spawn: for the first
few seconds the monster does not aggro and does not move, to have time to look around;
the threshold is taken either as a number or from a class parameter.
Signature
GetLifeTime( )Parameters
(none — the function is called without arguments)Example
if ( GetLifeTime( ) > 7 ) {Usage example
if ( GetLifeTime( ) >= ( Rand( 5 ) + 3 ) && InMyTerritory( myself.sm ) ) {
AddAttackDesire( creature, @AMT_MOVE_TO_TARGET, 200 );
}GetTimeHourNPC🟢 high
Returns the current in-game hour (0..23) by the accelerated in-game clock — the same
as GetL2Time(@L2F_HOUR). No arguments, called on myself. In old
scripts "day or night" is checked by a threshold (hour five and above — day, less — night),
but it is more reliable to ask directly GetL2Time(@L2F_IS_NIGHT) (returns 1 at night, 0 during the day).
Not to be confused with GetTimeOfDay — that returns the raw server timestamp in seconds.
Signature
GetTimeHour( )Parameters
(none — the function is called without arguments)Example
if (GetTimeHour() < 5)Usage example
if (GetTimeHour() < 6)
{
CreateOnePrivateEx(@sf_halloween21_vampire1 + Rand(4), "sf_halloween21_vampire", 0, 0, FloatToInt(myself.sm.x + 30), FloatToInt(myself.sm.y + 30), FloatToInt(myself.sm.z), 0, 0, 0, 0);
CreateOnePrivateEx(@sf_halloween21_vampire1 + Rand(4), "sf_halloween21_vampire", 0, 0, FloatToInt(myself.sm.x - 30), FloatToInt(myself.sm.y - 30), FloatToInt(myself.sm.z), 0, 0, 0, 0);
}STATE STORAGE (GlobalMap / DBSavingMap / DBValue)
8 functionsRegisterDBSavingMapGLOBAL🟢 high
Writes a "key — number" pair to the persistent map whose value is stored
in the DB and survives a restart; used for counters that must not be lost.
Takes arguments (int key, int value) in the gg namespace (CGlobalObject);
returns an integer.
Related event: reading (LoadDBSavingMap) responds with the event LOAD_DBSAVING_MAP_RETURNED(i0=key, i1=value) (see NASC_HANDLERS).
Signature
RegisterDBSavingMap( int nMapKey, int nValue )Parameters
nMapKey (int) — map key: a @gm_* constant [manual_pch] or a raw number.
nValue (int) — number stored in the persistent DB map under this key.Example
RegisterDBSavingMap(@gm_supply_box, i2);Usage example
if ( myself.i_ai2 == 1 ) {
RegisterDBSavingMap( GM_ID1, Castle_GetRawSystemTime( ) );
myself.i_ai0 = Castle_GetRawSystemTime( );
myself.i_ai1 = 0;
myself.i_ai2 = 2;
}GetDBSavingMapGLOBAL🟢 high
Reads the number stored under a key in the persistent DB map. Takes argument
(int key) in the gg namespace (CGlobalObject); returns the stored number.
Signature
GetDBSavingMap( int nMapKey )Parameters
nMapKey (int) — map key: a @gm_* constant [manual_pch] or a raw number.Example
i1 = GetDBSavingMap(@gm_supply_box);Usage example
i1 = GetDBSavingMap(@gm_supply_carriage);
if ((i1 % 10) >= 1) {
i2 = i1 - 1;
RegisterDBSavingMap(19, i2);
}LoadDBSavingMapGLOBAL🟢 high
Initiates an ASYNCHRONOUS load of a creature's saved data map from the database (by character
identifier). The first argument — the creature whose data to load — determines whose record to fetch
from the DB. The function does NOT return a value directly: the result arrives as a separate event, after
which the data is available via the Get functions. So in scripts, Load merely starts loading into
the cache, and reading happens later. Called on gg.
Signature
LoadDBSavingMap( CSharedCreatureData cCreature, int nMapKey )Parameters
cCreature (CSharedCreatureData) — creature in whose context the value is loaded.
nMapKey (int) — map key: a @gm_* constant [manual_pch] or a raw number.Example
LoadDBSavingMap(myself.sm, @gm_hot_spot);
Related event: the server's response arrives as the LOAD_DBSAVING_MAP_RETURNED event (see NASC_HANDLERS).RegisterGlobalMapNPC🟢 high
Writes a "key — number" pair to the in-memory server cache with which NPCs exchange
state on the fly. Takes the arguments (int key, int value) in the myself namespace
(CNPC); returns nothing. The cache is reset on a server restart.
Signature
RegisterGlobalMap( int key, int value )Parameters
key (int) — the record key in the server state cache
value (int) — the number saved in the global map under the given keyExample
RegisterGlobalMap(@gm_cartia, myself.sm.id);Usage example
if ( i0 == -1 ) {
RegisterGlobalMap( GM_ID, GetIndexFromCreature( myself.sm ) );
}GetGlobalMapNPC🟢 high
Reads a number previously written by key to the global map. Takes the argument
(int key) in the myself namespace (CNPC); returns the stored number or -1 if
the key is absent.
Signature
GetGlobalMap( int key )Parameters
key (int) — the key by which the number is read from the global mapExample
i0 = GetGlobalMap(@gm_cartia);Usage example
i0 = GetGlobalMap( @gm_frintessa );
if ( i0 != -1 ) { c0 = GetCreatureFromIndex( i0 ); }UnregisterGlobalMapNPC🟢 high
Deletes the record by key from the in-memory global map. Takes the argument (int key)
in the myself namespace (CNPC); returns an integer.
Signature
UnregisterGlobalMap( int key )Parameters
key (int) — the key whose record is deleted from the global mapExample
UnregisterGlobalMap(@i_core);Usage example
if ( c0.db_value == 0 ) {
UnregisterGlobalMap( myself.i_ai2 );
Despawn( );
}SetDBValueNPC🟢 high
Saves for the creature c (most often myself.sm) a permanent number — for example,
a stage number that the NPC remembers between re-logins. Takes the arguments
(CSharedCreatureData c, int nValue) in the myself namespace (CNPC); returns nothing.
There is no reverse read function — the written value is read through the creature's .db_value field.
Signature
SetDBValue( CSharedCreatureData c, int nValue )Parameters
c (CSharedCreatureData) — the creature (usually `myself.sm`) for which the number is saved.
nValue (int) — the permanent number saved for the creature (read through the `.db_value` field).Example
SetDBValue( myself.sm, @SCE_FRINTESSA_ALL_READY );Usage example
if ( myself.sm.db_value == 1 ) {
SetDBValue( myself.sm, 0 );
}DATA STORAGE (DbData / DbCookie / AtomicValue)
16 functionsCompareExchangeGLOBAL🟢 high
A method of the thread-safe counter CAtomicValue (per decompile — _InterlockedCompareExchange). If
the current value matches the expected one (the SECOND argument — the comparand), it swaps it for the new one
(the FIRST argument) and returns the old one; if it does not match — leaves it as is and returns the current one.
The basis of lock-free flags: in one operation you safely "capture" a state without a race.
Signature
CompareExchange( int nNew, int nComparand )Parameters
nNew (int) — the new value written into the counter on a match.
nComparand (int) — the expected value: compared with the counter's current content (on equality — a swap).
Example: av_ai0.CompareExchange(1, 0) — if the counter == 0, write 1 and return the old (0).Example
if (myself.av_ai0.CompareExchange(1, 0) == 0)Usage example
if ( myself.av_quest0.CompareExchange( GetIndexFromCreature( talker ), 0 ) == 0 ) {
CheckSubJobAsMain( talker, i10 );
}DecrementGLOBAL🟢 high
A method of CAtomicValue: atomically decreases the counter by nAmount and returns the new value
(per decompile — _InterlockedExchangeAdd(-nAmount); the counter itself is an atomic object, e.g. av_ai0).
Under the hood — an aligned integer field and hardware interlocked instructions.
Signature
Decrement( int nAmount )Parameters
nAmount (int) — by how much to decrease the counter (1 in calls).Example
myself.av_ai0.Decrement(1);SetMaxSizeGLOBAL🟢 high
A method of a list (integer or string): sets the maximum size. Called before
filling the list.
Signature
SetMaxSize( int nMaxSize )Parameters
nMaxSize (int) — the maximum size of the listExample
myself.int_list.SetMaxSize(100);SetAsNullGLOBAL🟢 high
Nulls out an object reference — used to clear temporary references to creatures like c_ai0/c_ai1.
Signature
SetAsNull( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature reference being nulled out (for example `c_ai0`/`c_ai1`)Example
SetAsNull( myself.c_ai1 );LoadDBNpcInfoMAKER🟢 high
Pulls saved NPC data from the database into a spawn-define object by a
numeric key. Called on the define itself: first the maker iterates its own
spawn-defines via GetSpawnDefine, for each checks whether it is bound to the database (the field
has_dbname), and only for the bound ones calls LoadDBNpcInfo — otherwise there is nothing to load. After
this, the define holds the data from the database, and NPCs can be spawned from it already with the restored
state. The argument is the numeric key of the database record (1010 in calls).
Signature
LoadDBNpcInfo( int nNpcId )Parameters
nNpcId (int) — the numeric key of the database record whose data is pulled into the spawn define.Example
def0.LoadDBNpcInfo( 1010 );SetDBLoadedMAKER🟢 high
Sets the flag that the character/define data is already loaded from the database (1 — loaded,
0 — not).
Signature
SetDBLoaded( int nLoaded )Parameters
nLoaded (int) — the flag for loading data from the database: 1 — loaded, 0 — notExample
loaded_def.SetDBLoaded( 1 );GetDbCookieIntNPC🟢 high
Reads an integer value from a DbCookie group by key. The group is given by an identifier
(for example BuffCookieGroupID), the key — by a number. If the key is absent, zero is returned. The first
argument is the player, the second — the group, the third — the key.
Signature
GetDbCookieInt( CSharedCreatureData cCreature, int nGroupId, int nCookieId )Parameters
cCreature (CSharedCreatureData) — the player whose DbCookie value is read
nGroupId (int) — the cookie group identifier
nCookieId (int) — the key of the read value within the groupExample
i9 = GetDbCookieInt( talker, BuffCookieGroupID, 0 );Usage example
i5 = GetDbCookieInt(talker, BuffCookieGroupID, i1+1);
if ((i4 == i6) && (i5 == state)) { i0 = i2; i2 = i3+1; }SetDbCookieIntNPC🟢 high
Writes an integer value to a group by key and immediately saves it to the database. If the key did
not yet exist, it is created. Arguments: the player, the group identifier, the key, the value.
Signature
SetDbCookieInt( CSharedCreatureData cCreature, int nGroupId, int nCookieId, int64 nValue )Parameters
cCreature (CSharedCreatureData) — the player for whom the value is written to DbCookie
nGroupId (int) — the cookie group identifier
nCookieId (int) — the key of the written value within the group
nValue (int64) — the written valueExample
SetDbCookieInt(talker, @AbilityCheckCookieGroup, 7, 1);LoadDbCookieGroupNPC🟢 high
Loads one specified cookie group from the database and along the way calls an event about its loading.
Arguments: the player and the group identifier.
Signature
LoadDbCookieGroup( CSharedCreatureData cCreature, int nGroupId )Parameters
cCreature (CSharedCreatureData) — the player whose cookie group is loaded from the database
nGroupId (int) — the identifier of the loaded cookie groupExample
LoadDbCookieGroup( talker, BuffCookieGroupID );Usage example
if ( reply == 4 ) { // start working with buffs
LoadDbCookieGroup( talker, BuffCookieGroupID );
return;
}LoadDbCookieAllGroupsNPC🟢 high
Loads all of a character's cookie groups from the database at once. The single argument is the player.
Signature
LoadDbCookieAllGroups( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player all of whose cookie groups are loaded from the databaseExample
LoadDbCookieAllGroups(talker);DeleteDbCookieGroupNPC🟢 high
Deletes the specified cookie group entirely — both from memory and from the database. Arguments: the player and
the group identifier.
Signature
DeleteDbCookieGroup( CSharedCreatureData cCreature, int nGroupId )Parameters
cCreature (CSharedCreatureData) — the player from whom the cookie group is deleted
nGroupId (int) — the identifier of the deleted cookie groupExample
DeleteDbCookieGroup( talker, BuffCookieGroupID );Usage example
if ( reply == 8 ) { // deleting profileS
DeleteDbCookieGroup( talker, BuffCookieGroupID );
ShowPage( talker, fn_BuffProfilesDelOk );
return;
}SetDbDataNPC🟢 high
Works with an arbitrary database table. Takes a dozen string parameters: the first
play the role of keys, the rest — of data. Inserts a new row or updates an existing one.
The semantics of the keys and data are reconstructed from calls.
Signature
SetDbData( string pws1, string pws2, string pws3, string pws4, string pws5, string pws6, string pws7, string pws8, string pws9, string pws10 )Parameters
pws1 (string) — the first key parameter of the row (table name/primary key)
pws2 (string) — a key/data parameter of the row
pws3 (string) — a key/data parameter of the row
pws4 (string) — a key/data parameter of the row
pws5 (string) — a data parameter of the row
pws6 (string) — a data parameter of the row
pws7 (string) — a data parameter of the row
pws8 (string) — a data parameter of the row
pws9 (string) — a data parameter of the row
pws10 (string) — a data parameter of the row (unused ones passed as `_blank`)Example
SetDbData("za_monolit", "0", "0", "0", "0", "0", "0", "0", "0", s1);
SetDbData( config_ID, s0, "0", "0", "-1", "-1", "0", _blank, _blank, _blank );Usage example
if ( reply > 0 ) {
SetDbData( "SUB_USER", talker.name, "MAIN: " + talker.subjob0_class, "SUB1: " + talker.subjob1_class, "SUB2: " + talker.subjob2_class, "SUB3: " + talker.subjob3_class, "LV: " + talker.level, IntToStr( talker.dbid ), "reply: " + reply , "level: " + level );
} else {
SetDbData( "SUB_USER", talker.name, "Error on SET_SUBJOB_AS_MAIN", _blank, _blank, _blank, _blank, _blank, _blank, _blank );
}GetDbDataNPC🟢 high
Requests table rows by criteria (the same ten string parameters). The request is
asynchronous: the rows arrive not immediately, but later — in the return event, where the number of found
rows lies in the first integer parameter. Unused parameters are passed as _blank.
Signature
GetDbData( string pws1, string pws2, string pws3, string pws4, string pws5, string pws6, string pws7, string pws8, string pws9, string pws10 )Parameters
pws1 (string) — the first selection criterion (table name/key)
pws2 (string) — a row selection criterion
pws3 (string) — a row selection criterion
pws4 (string) — a row selection criterion
pws5 (string) — a row selection criterion
pws6 (string) — a row selection criterion
pws7 (string) — a row selection criterion
pws8 (string) — a row selection criterion
pws9 (string) — a row selection criterion
pws10 (string) — a row selection criterion (unused ones passed as `_blank`)Example
GetDbData( tiat_top_dbname, "top10", _blank, _blank, _blank, _blank, _blank, IntToStr( myself.i_quest9 ), _blank, _blank );
Related event: the server's response arrives as the GETDBDATA_RETURNED event (see NASC_HANDLERS).DelDbDataNPC🟢 high
Deletes from a table the rows matching the passed criteria (ten string
parameters, unused ones — _blank).
Signature
DelDbData( string pws1, string pws2, string pws3, string pws4, string pws5, string pws6, string pws7, string pws8, string pws9, string pws10 )Parameters
pws1 (string) — the first deletion criterion (table name/key)
pws2 (string) — a row deletion criterion
pws3 (string) — a row deletion criterion
pws4 (string) — a row deletion criterion
pws5 (string) — a row deletion criterion
pws6 (string) — a row deletion criterion
pws7 (string) — a row deletion criterion
pws8 (string) — a row deletion criterion
pws9 (string) — a row deletion criterion
pws10 (string) — a row deletion criterion (unused ones passed as `_blank`)Example
DelDbData( db_type, s0, s1, _blank, _blank, _blank, _blank, _blank, _blank, _blank );Usage example
if ( i2 == 0 && (i0 == 0) && (i1 == 0) ) { // change the season on Sunday, at 00:00
DelDbData( tiat_top_dbname_season, IntToStr( myself.i_quest9 ), _blank, _blank, _blank, _blank, _blank, _blank, _blank, _blank ); // delete the record about the previous season
myself.i_quest9 = myself.i_quest9 + 1;
SetDbData( tiat_top_dbname_season, IntToStr( myself.i_quest9 ), _blank, _blank, _blank, _blank, _blank, _blank, _blank, _blank ); // write the current value
}DelDbDataByIdNPC🟢 high
Deletes one table row by its numeric identifier — the fastest way to delete.
Signature
DelDbDataById( int nId )Parameters
nId (int) — the numeric identifier of the deleted table rowExample
DelDbDataById( myself.db_int_list.Get( i1 ) );
DelDbDataById( myself.db_int_list.Get( 0 ) );Usage example
for( i1=0; i1<i0; ++i1 ) {
DelDbDataById( myself.db_int_list.Get( i1 ) );
}GetAllUserForInZoneNPC🟢 high
Requests the list of all players in the current zone. The list arrives asynchronously — in an event,
where each player becomes a target, and their total number lies in the first integer parameter.
Signature
GetAllUserForInZone( )Parameters
(none — the function is called without arguments)Example
GetAllUserForInZone( );Usage example
if (myself.sm.flag != 2) {
GetAllUserForInZone();
myself.av_ai0.Increment(1);
AddTimerEx(1001, 1000);
}NR-MEMO / LOG / COOKIE (persistent state memory)
14 functionsHaveNRMemoGLOBAL🟢 high
Checks whether the given quest/event's NR marker is set on the player. Arguments: the player and
nQuestId ([quest_pch], a @-constant). Returns 1 if the marker exists, otherwise 0.
Signature
HaveNRMemo( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — the player whose NR marker is checked
nQuestId (int) — the choice of quest/event whose marker presence is checked (a quest `@`-constant)
the values are from the [quest_pch] dictionaryExample
if (HaveNRMemo(talker, @dominion_war_state) == @FALSE)Usage example
if (HaveNRMemo(talker, @defend_catapult_of_dom) == @TRUE)
{
SetNRMemoState(talker, @defend_catapult_of_dom, 100);
}GetNRMemoStateGLOBAL🟢 high
Reads the numeric NR state bound to a quest/event (the persistent analog of GetMemoState).
Arguments: the player and nQuestId ([quest_pch], a @-constant). Returns the stored number.
Signature
GetNRMemoState( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — the player whose NR state is read
nQuestId (int) — the choice of quest/event whose state is read (a quest `@`-constant)
the values are from the [quest_pch] dictionaryExample
i0 = GetNRMemoState(talker, @dominion_war_state);Usage example
i6 = GetNRMemoState(talker, i10);
if (i6 >= 0)
{
i7 = GetNRMemoState(talker, @dominion_war_state);
SetNRMemoState(talker, @dominion_war_state, (i6 + i7));
RemoveNRMemo(talker, i10);
AddLog(2, talker, i10);
}GetNRMemoStateExGLOBAL🟢 high
Reads an additional NR-state slot (several cells per one quest, like GetMemoStateEx).
Arguments: the player, nQuestId ([quest_pch], a @-constant), and nSlot — the slot number. Returns
the number stored in the slot.
Signature
GetNRMemoStateEx( CSharedCreatureData cCreature, int nQuestId, int nSlot )Parameters
cCreature (CSharedCreatureData) — the player whose additional NR-state slot is read
nQuestId (int) — the choice of quest/event whose state is read (a quest `@`-constant)
the values are from the [quest_pch] dictionary
nSlot (int) — the number of the additional state slotExample
if (i4 != GetNRMemoStateEx(talker, @dominion_war_state, 1))Usage example
if (i4 != GetNRMemoStateEx(talker, @dominion_war_state, 1))
{
SetNRMemoState(talker, @dominion_war_state, 0);
SetNRMemoStateEx(talker, @dominion_war_state, 1, i4);
}SetNRMemoNPC🟢 high
Sets on the player the NR marker "contact with a quest/event" — an analog of SetMemo, but persistent
(not reset when quests are cleared). Arguments: the player and nQuestId (resolved from
[quest_pch], i.e. a @-constant of the quest/event). Returns an int.
Signature
SetNRMemo( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — the player on whom the NR marker is set
nQuestId (int) — the choice of quest/event whose marker is set (a quest `@`-constant)
the values are from the [quest_pch] dictionaryExample
SetNRMemo(talker, @dominion_war_state);Usage example
if (GetDailyQuestFlag(target, @destory_shield) == @TRUE) {
SetNRMemo(target, @destory_shield);
AddLog(1, target, @destory_shield);
SetNRMemoState(target, @destory_shield, i5);
ShowOnScreenMsgFStr(target, 2, 0, 0, 0, 1, 0, 5000, 0, 73451, IntToStr(i5), _blank, _blank, _blank, _blank);
}RemoveNRMemoNPC🟢 high
Removes from the player a previously set NR marker (an analog of RemoveMemo). Arguments: the player and
nQuestId ([quest_pch], a @-constant of the quest/event). Returns an int.
Signature
RemoveNRMemo( CSharedCreatureData cCreature, int nQuestId )Parameters
cCreature (CSharedCreatureData) — the player from whom the NR marker is removed
nQuestId (int) — the choice of quest/event whose marker is removed (a quest `@`-constant)
the values are from the [quest_pch] dictionaryExample
RemoveNRMemo(talker, @defend_catapult_of_dom);Usage example
if ( HaveNRMemo( talker, @defend_catapult_of_dom ) == 1 ) {
RemoveNRMemo( talker, @defend_catapult_of_dom );
AddLog( 2, talker, 729 );
}SetNRMemoStateNPC🟢 high
Writes a numeric NR state for a quest/event (a persistent analog of SetMemoState).
Arguments: the player, nQuestId ([quest_pch], a @-constant), and nValue — the written number.
Returns an int.
Signature
SetNRMemoState( CSharedCreatureData cCreature, int nQuestId, int nValue )Parameters
cCreature (CSharedCreatureData) — the player whose NR state is written
nQuestId (int) — the choice of quest/event for which the state is written (a quest `@`-constant)
the values are from the [quest_pch] dictionary
nValue (int) — the written numeric stateExample
SetNRMemoState(talker, @dominion_war_state, 0);Usage example
if (HaveNRMemo(talker, @defend_catapult_of_dom) == @TRUE) {
SetNRMemoState(talker, @defend_catapult_of_dom, i0);
SetNRMemoStateEx(talker, @defend_catapult_of_dom, 1, i3);
AddLog(1, talker, @defend_catapult_of_dom);
ShowQuestMark(talker, @defend_catapult_of_dom);
SoundEffect(talker, "ItemSound.quest_middle");
}SetNRMemoStateExNPC🟢 high
Writes a value into an additional NR-state slot (several cells per quest, like
SetMemoStateEx). Arguments: the player, nQuestId ([quest_pch], a @-constant), nSlot — the slot number,
and nValue — the written number. Returns an int.
Signature
SetNRMemoStateEx( CSharedCreatureData cCreature, int nQuestId, int nSlot, int nValue )Parameters
cCreature (CSharedCreatureData) — the player whose additional NR-state slot is written
nQuestId (int) — the choice of quest/event for which the state is written (a quest `@`-constant)
the values are from the [quest_pch] dictionary
nSlot (int) — the number of the additional state slot
nValue (int) — the number written into the slotExample
SetNRMemoStateEx(talker, @dominion_war_state, 1, i4);GetNRMemoCountNPC🟢 high
Returns the number of NR markers set on the player (a persistent analog of GetMemoCount).
The single argument is the player. Returns an int.
Signature
GetNRMemoCount( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose number of NR markers is counted
Example: there are no direct calls in our scripts.SetNRFlagJournalNPC🟢 high
Sets a flag (bit/step) of the NR-event journal — a visible progress mark (an analog of
SetFlagJournal). Arguments: the player, nQuestId ([quest_pch], a @-constant or a variable with the id), and
nFlag — the flag-step (in calls accumulated with values like 3..11). Returns nothing.
Signature
SetNRFlagJournal( CSharedCreatureData cCreature, int nQuestId, int nFlag )Parameters
cCreature (CSharedCreatureData) — the player for whom the NR-event journal flag is set
nQuestId (int) — the choice of quest/event whose journal is marked (a quest `@`-constant)
the values are from the [quest_pch] dictionary
nFlag (int) — the set journal progress flag-stepExample
SetNRFlagJournal(talker, i10, 1);SetJournalNPC🟢 high
Sets an ordinary (resettable) quest-journal flag-step — a visible progress mark.
Arguments: the player, nQuestId ([quest_pch], a @-constant), and nStep — the step number. Returns
nothing.
Signature
SetJournal( CSharedCreatureData cCreature, int nQuestId, int nStep )Parameters
cCreature (CSharedCreatureData) — the player for whom the quest journal flag is set
nQuestId (int) — the choice of quest whose journal is marked (a quest `@`-constant)
the values are from the [quest_pch] dictionary
nStep (int) — the number of the set journal stepExample
SetJournal( talker, @the_wishing_potion, 1 );GetHTMLCookieNPC🟢 high
Reads the "cookie" of dialog/quest stage progress bound to the shown HTML. Arguments:
the player, nQuestId ([quest_pch], a @-constant), and nIndex — the stage/cookie number. Returns -1
if the stage is not yet marked.
Signature
GetHTMLCookie( CSharedCreatureData cCreature, int nQuestId, int nIndex )Parameters
cCreature (CSharedCreatureData) — the player whose dialog/quest stage cookie is read
nQuestId (int) — the choice of quest to which the stage is bound (a quest `@`-constant)
the values are from the [quest_pch] dictionary
nIndex (int) — the stage/cookie numberExample
i0 = GetHTMLCookie( talker, @the_ocean_of_distant_stars, 3 );SetHTMLCookieNPC🟢 high
Marks that the player has passed a dialog/quest stage (a cookie of the shown HTML), so that on a repeat
entry the dialog immediately shows the needed page. Arguments: the player, nQuestId ([quest_pch],
a @-constant), and nIndex — the stage/cookie number. Returns nothing.
Signature
SetHTMLCookie( CSharedCreatureData cCreature, int nQuestId, int nIndex )Parameters
cCreature (CSharedCreatureData) — the player for whom the passed dialog/quest stage is marked
nQuestId (int) — the choice of quest to which the stage is bound (a quest `@`-constant)
the values are from the [quest_pch] dictionary
nIndex (int) — the stage/cookie numberExample
SetHTMLCookie( talker, @the_ocean_of_distant_stars, 3 );Usage example
if ( GetMemoState( talker, @into_the_flame ) == ( ( 2 * 10 ) + 2 ) && OwnItemCount( talker, @q_vacualite_ore ) >= 50 ) {
SetHTMLCookie( talker, 618, 2 );
ShowPage( talker, "blacksmith_byron_q0618_0202.htm" );
} else {
ShowPage( talker, "blacksmith_byron_q0618_0203.htm" );
}GetCookieNPC🟢 high
Reads an arbitrary named state value on the player by a string key (unlike
memo/HTML-cookie, the key is given by a string, not a quest-id). Arguments: the player and sKey —
the string key. Returns the stored number.
Signature
GetCookie( CSharedCreatureData cCreature, string sKey )Parameters
cCreature (CSharedCreatureData) — the player whose named state is read
sKey (string) — the string key of the read valueExample
if ( OwnItemCount( talker, @adena ) >= GetCookie( talker, "AgitDecoFee" ) ) {Usage example
i1 = GetCookie( talker, "gate_level" );
if ( i0 == 1 && i1 == 200 ) {
i2 = DDoorPrice1_1;
}SetCookieNPC🟢 high
Writes an arbitrary named state value on the player by a string key — into it the
script saves computed parameters between dialog steps (a service price, a branch choice, zone/gate
numbers, a manor id). Arguments: the player, sKey — the string key, and nValue — the written number.
Signature
SetCookie( CSharedCreatureData cCreature, string sKey, int nValue )Parameters
cCreature (CSharedCreatureData) — the player for whom the named state is written
sKey (string) — the string key of the written value
nValue (int) — the written numberExample
SetCookie( talker, "AgitDecoFee", Agit_GetDecoFee( i0, i1 ) );Usage example
if ( reply == 2 ) {
SetCookie( talker, "dmgzone_num", 2 );
}CASTLES, SIEGES, AND FORTRESSES (Castle / Siege / Fortress)
53 functionsFortress_GetOwnerPledgeIdGLOBAL🟢 high
Returns the id of the clan owning fortress nFortressId. If the fortress is not captured by anyone — returns 0,
so checking the result > 0 tells whether the fortress has an owner.
Signature
Fortress_GetOwnerPledgeId( int nFortressId )Parameters
nFortressId (int) — identifier of the fortress whose owning clan is queriedUsage example
if ( Fortress_GetOwnerPledgeId( fortress_id ) > 0 ) {
return;
}Fortress_GetParentCastleIdGLOBAL🟢 high
Returns the identifier of the fortress's parent castle. Purpose inferred from the name;
direct calls were not analyzed.
Signature
Fortress_GetParentCastleId( int nFortressId )Parameters
nFortressId (int) — identifier of the fortress whose parent castle is queriedExample
Fortress_GetParentCastleId(fortress_id);Fortress_GetFacilityLevelGLOBAL🟢 high
Returns the level of the specified facility of fortress nFortressId. A fortress has five facility
types (nFacilityType 0..4, see below); for an unknown type -1 is returned. The level
shows how upgraded the facility is (guard reinforcement, gates, etc.).
Signature
Fortress_GetFacilityLevel( int nFortressId, int nFacilityType )Parameters
nFortressId (int) — identifier of the fortress whose facilities are queried
nFacilityType (int) — fortress facility type. Values @FORTRESS_* [manual_pch]:
0 GUARD_REINFORCEMENT · 1 GUARD_POWER_UP · 2 DOOR_POWER_UP · 3 PHOTOCANNON · 4 SCOUTUsage example
i0 = Fortress_GetFacilityLevel( fortress_id, facility_type );
if ( i0 < facility_level ) {
return;
}Fortress_GetRentCostGLOBAL🟢 high
Returns the maintenance cost of fortress nFortressId — the amount (in adena) that the owning clan
periodically pays to keep the fortress. Used in fortress manager dialogs to display
and deduct the fee.
Signature
Fortress_GetRentCost( int nFortressId )Parameters
nFortressId (int) — identifier of the fortress whose maintenance cost is returnedExample
i6 = Fortress_GetRentCost( fortress_id );GetDominionStateGLOBAL🟢 high
Returns the state code of the territory war (Dominion) for territory nResidenceId.
Non-zero values correspond to active phases of the siege cycle: in the example, states 1 and 2
enable additional respawn of objects on the territory.
Signature
GetDominionState( int nResidenceId )Parameters
nResidenceId (int) — identifier of the residence/territory whose state is queriedUsage example
i1 = GetDominionState(dominion_id);
if (i1 == 1 || i1 == 2) {
if (deleted_def.respawn_time != 0) {
if (AtomicIncreaseTotal(deleted_def, 1, 1)) {
deleted_def.Spawn2(1, deleted_def.respawn_time, deleted_def.respawn_rand);
}
}
}Castle_GetPledgeStateNPC🟢 high
Returns the creature c's relation to this NPC's castle — the basis of the "friend or foe" logic
during a siege. The argument c (CSharedCreatureData) — whom we check. A value of 2 means
belonging to the side owning the castle (a member of the owner clan or a defender): guards
do not attack those whose state is 2, and are hostile to the rest; for summons the state of
their owner (attacker.master) is checked.
Signature
Castle_GetPledgeState( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — whom we check.Example
if (IsInCategory(@summon_npc_group, speller.npc_class_id) != 0 && Castle_GetPledgeState(speller.master) == 2) {Usage example
if ( Castle_GetPledgeState( creature ) != 2 ) {
AddAttackDesire( creature, @AMT_STAND, 200 );
}Castle_IsUnderSiegeNPC🟢 high
Returns whether this NPC's castle is currently under siege (1/0), no arguments. By this flag
guards switch behavior between peaceful and combat mode (aggression to foes,
opening or closing gates). There is a version Castle_IsUnderSiege2(nCastleId) — for
a specific castle by identifier.
Signature
Castle_IsUnderSiege( )Parameters
(none — the function is called without arguments)Example
if (Castle_IsUnderSiege() == @TRUE)Usage example
if ( Castle_IsUnderSiege( ) != 0 ) {
Say( "Castle is Under Attack..." );
}Castle_GetPledgeIdNPC🟢 high
Returns the identifier of this NPC's castle's owner clan, no arguments. It is often
compared with the player's affiliation (talker.pledge_id), so that together with a
clan-privilege check it decides whether the player belongs to the owning clan.
Signature
Castle_GetPledgeId( )Parameters
(none — the function is called without arguments)Example
if (Castle_GetPledgeId())Usage example
if ( Castle_GetPledgeId( ) == talker.pledge_id && talker.pledge_id != 0 ) {
ShowPage( talker, "farm_kel_mahum_messenger_25.htm" );
return;
}Castle_GetPledgeNameNPC🟢 high
Returns a string with the name of this NPC's castle's owner clan, no arguments.
Used to show the player information about the castle's owner.
Signature
Castle_GetPledgeName( )Parameters
(none — the function is called without arguments)Example
FHTML_SetStr(fhtml0, "my_pledge_name", Castle_GetPledgeName());Castle_GetOwnerNameNPC🟢 high
Returns a string with the name of this NPC's castle's owner itself, no arguments.
Used to show the player information about the owner.
Signature
Castle_GetOwnerName( )Parameters
(none — the function is called without arguments)Example
FHTML_SetStr(fhtml0, "my_owner_name", Castle_GetOwnerName());Castle_GateOpenCloseNPC🟢 high
Opens or closes the gates of this NPC's castle. The argument nState (int, from [manual_pch])
sets the state: @CGOC_OPEN=0 open, @CGOC_CLOSE=1 close. Available to the owner
or a lord with the privilege @PP_OPEN_CASTLE_DOOR. The global variants
Castle_GateOpenClose2(sGate, nState) and ...Ex(sGate, nState, nZoneId) (on gg)
address specific gates by name — see the doors, gates, and areas group.
Signature
Castle_GateOpenClose( int nState )Parameters
nState (int) — the gate state (manual_pch):
@CGOC_OPEN (0) — open; @CGOC_CLOSE (1) — close.Example
Castle_GateOpenClose(@CGOC_OPEN);
Castle_GateOpenClose( 0 );
Castle_GateOpenClose( 1 );
Castle_GateOpenClose(@CGOC_CLOSE);Castle_GetSiegeTimeNPC🟢 high
Returns a string with the time of the castle's nearest siege, no arguments. Intended for
showing to the player.
Signature
Castle_GetSiegeTime( )Parameters
(none — the function is called without arguments)Example
if (Castle_GetSiegeTime() != "")Usage example
if ( Castle_GetSiegeTime( ) != _blank ) {
FHTML_SetFileName( fhtml0, "farm_messenger_q0655_11.htm" );
FHTML_SetStr( fhtml0, "next_siege", Castle_GetSiegeTime( ) );
ShowFHTML( talker, fhtml0 );
}RegisterSiegeNPC🟢 high
Registers the clan of the player c (CSharedCreatureData) as a siege attacker. Returns
nothing.
Signature
RegisterSiege( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose clan is registered as a siege attacker
Example (illustrative):
RegisterSiege( talker );RegisterSiegeDefenderNPC🟢 high
By design — registers the clan of the player c (CSharedCreatureData) as a castle siege defender. IMPORTANT: in
this server build (CT2.3) the call actually does nothing — like the whole castle siege registration
family (RegisterSiege/UnregisterSiege/CheckSiege), the recording of defenders has been moved to the community board.
The function is left for compatibility with old scripts.
Signature
RegisterSiegeDefender( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose clan is registered as a siege defender
Example (illustrative):
RegisterSiegeDefender( talker );OpenSiegeInfoNPC🟢 high
Opens for the player c (CSharedCreatureData) a window with siege information. Returns
nothing.
Signature
OpenSiegeInfo( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player for whom the siege information window is openedExample
OpenSiegeInfo(talker);Usage example
if ( IsMyLord( talker ) || ( HavePledgePower( talker, @ppSiege ) && Castle_GetPledgeId( ) == talker.pledge_id && talker.pledge_id != 0 ) ) {
OpenSiegeInfo( talker );
} else {
ShowPage( talker, fnNoAuthority );
}Castle_BanishOthersNPC🟢 high
Banishes from this NPC's castle (residence) zone all outsiders — players not in the
owner clan. No arguments: the residence is taken by the NPC itself. Corresponds to the
"Banish Outsiders" button in the castle management menu.
Signature
Castle_BanishOthers( )Parameters
(none — the function is called without arguments)Example
Castle_BanishOthers();Usage example
if ( IsMyLord( talker ) || ( HavePledgePower( talker, @ppClanHallBanish ) && Castle_GetPledgeId( ) == talker.pledge_id && talker.pledge_id != 0 ) ) {
Castle_BanishOthers( );
ShowPage( talker, fnAfterBanish );
} else {
ShowPage( talker, fnNoAuthority );
}Castle_GetHPRegenNPC🟢 high
Returns the level (grade) of the installed residence function "HP Restore" of this NPC's
castle. This is one of the paid residence functions (an analog of clan hall functions): its level
is set by Castle_SetHPRegen and determines the strength of the HP regeneration bonus on the territory. No
arguments — works by the NPC's own residence; if the function is not installed, returns 0.
Signature
Castle_GetHPRegen( )Parameters
(none — the function is called without arguments)Example
Castle_GetHPRegen( );Castle_SetHPRegenNPC🟢 high
Installs (or removes) the residence function "HP Restore" of the castle at the given level.
At nLevel>0 the function is enabled for 7 days; at nLevel=0 — it is removed. The residence is taken by
the NPC itself.
Signature
Castle_SetHPRegen( int nLevel )Parameters
nLevel (int) — the level (grade) of the residence's HP restore function; >0 — install for
7 days, 0 — remove the function.
Example (illustrative):
Castle_SetHPRegen( nLevel );Castle_GetMPRegenNPC🟢 high
Returns the level (grade) of the installed residence function "MP Restore" of this NPC's
castle — an analog of Castle_GetHPRegen for MP (a function of type 1). The level is set by Castle_SetMPRegen and
determines the strength of the MP regeneration bonus on the territory. No arguments — by the NPC's own
residence; if the function is not installed, returns 0.
Signature
Castle_GetMPRegen( )Parameters
(none — the function is called without arguments)Example
Castle_GetMPRegen( );Castle_SetMPRegenNPC🟢 high
Installs (or removes) the residence function "MP Restore" of the castle at the given level —
an analog of Castle_SetHPRegen for MP. At nLevel>0 the function is enabled for 7 days; at nLevel=0 —
it is removed. The residence is taken by the NPC itself.
Signature
Castle_SetMPRegen( int nLevel )Parameters
nLevel (int) — the level (grade) of the residence's MP restore function; >0 — install for
7 days, 0 — remove the function.
Example (illustrative):
Castle_SetMPRegen( nLevel );Castle_GetLifeControlLevelNPC🟢 high
Returns the configured "life control" level of this NPC's castle/residence (no arguments —
works by the NPC's own residence). If the NPC has no bound residence, returns 0; otherwise it
reads the level from the residence's static data. This is an upgrade-level getter (affects the tier
of the regeneration bonus on the castle's territory); the bonus itself is applied by other code.
Signature
Castle_GetLifeControlLevel( )Parameters
(none — the function is called without arguments)Example
if (Castle_IsUnderSiege() == @TRUE && Castle_GetLifeControlLevel() == 0) {Usage example
if ( Castle_IsUnderSiege( ) && Castle_GetLifeControlLevel( ) == 0 ) {
ShowPage( talker, fnBrokenCtrlTower );
} else {
ShowPage( talker, fnHi );
}Castle_GetRawSiegeTimeNPC🟢 high
Returns the "raw" start time of this NPC's castle's nearest siege — as an integer timestamp
in seconds (unlike the formatted Castle_GetSiegeTime). Convenient for arithmetic with
time: in the example below a quest script compares it with the system time (Castle_GetRawSystemTime)
and with a saved memo mark, to catch a daily window (86400 s) and make sure the siege is still in the
future. No arguments — by the NPC's own castle.
Signature
Castle_GetRawSiegeTime( )Parameters
(none — the function is called without arguments)Usage example
if ( _from_choice == 0 || ( HaveMemo( talker, @competition_for_the_bandit_stronghold ) == 1 && OwnItemCount( talker, @q_contest_certificate ) > 0 && OwnItemCount( talker, @q_tarlk_amulet ) < 30 && ( Castle_GetRawSiegeTime( ) - GetMemoState( talker, @competition_for_the_bandit_stronghold ) ) < 86400 && ( Castle_GetRawSiegeTime( ) - Castle_GetRawSystemTime( ) ) > 0 ) ) {
SetCurrentQuestID( @competition_for_the_bandit_stronghold );
ShowPage( talker, "azit_messenger_q0504_07.htm" );
}Castle_SetSiegeTimeNPC🟢 high
Sets the date/time of the castle's nearest siege. Per the L2NPC decompile (CNPC::Castle_SetSiegeTime_48B04C)
the engine takes the nearest "siege" day, zeroes it to midnight, then adds offsets from the
arguments and sends the server the computed timestamp (packet opcode 13). The first two arguments are
boolean shifts (+1 day and +12 hours), the last two are the hour and minute of the siege start.
Signature
Castle_SetSiegeTime( int nAddDay, int nAddHalfDay, int nHour, int nMinute )Parameters
nAddDay (int) — the base-day shift: 1 = +1 day, 0 = no shift (engine: +86400 s).
nAddHalfDay (int) — a half-day shift: 1 = +12 hours, 0 = no shift (engine: +43200 s).
nHour (int) — the siege start hour (added as 3600·nHour).
nMinute (int) — the siege start minute (added as 60·nMinute).
Example (illustrative):
Castle_SetSiegeTime( nAddDay, nAddHalfDay, nHour, nMinute );ShowSetSiegeTimeNPC🟢 high
Shows the player one of three HTML pages depending on the siege state of this NPC's
residence. Per the L2NPC decompile (CNPC::ShowSetSiegeTime_4ACEE8) the engine reads the
residence data and calls ShowPage with one of three pages: if a siege is already scheduled for the
future — the third page; otherwise if the flag "time was already scheduled in the current cycle" is set —
the second; otherwise (the time can be set) — the first. That is, the three arguments are the names of HTML pages,
not the time text.
Signature
ShowSetSiegeTime( CSharedCreatureData c, string sPageCanSet, string sPageRegistered, string sPageScheduled )Parameters
c (CSharedCreatureData) — the player who is shown the page.
sPageCanSet (string) — the HTML page when no siege is scheduled and the time can be set (the default branch).
sPageRegistered (string) — the HTML page when the flag "time was already scheduled in the current cycle" is set.
sPageScheduled (string) — the HTML page when a siege is already scheduled for the future (the time is in the future).
Example (illustrative):
ShowSetSiegeTime( talker, "", "", "" );Castle_GetRelatedFortressListNPC🟢 high
Requests the list of fortresses "related" to this NPC's castle — fortresses that have concluded a contract/agreement
with the castle. The function is asynchronous: the result arrives as a separate event (see below). The argument c —
the request's context creature.
Signature
Castle_GetRelatedFortressList( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature by whose castle the list of related fortresses is takenExample
Castle_GetRelatedFortressList(talker);
Related event: the server's response arrives as the GET_RELATED_FORTRESS_LIST_RETURNED event (see NASC_HANDLERS).CheckSiegeNPC🟢 high
By design — checks the creature c's clan's registration for a castle siege. IMPORTANT: in this server build
(CT2.3) the call actually does nothing — the registration and checking of castle sieges have been moved to the
community board. The function is left for compatibility with old scripts.
Signature
CheckSiege( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature whose clan registration is checked for a siege
Example (illustrative):
CheckSiege( talker );UnregisterSiegeNPC🟢 high
By design — removes the creature c's clan's registration for a castle siege. IMPORTANT: in this server build
(CT2.3) the call actually does nothing — the castle siege registration (and its cancellation) has been moved to the
community board. The function is left for compatibility with old scripts.
Signature
UnregisterSiege( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature whose clan registration is removed from the siege
Example (illustrative):
UnregisterSiege( talker );ViewSiegeListNPC🟢 high
Shows the player c the list of registered sieges, rendered into the passed HTML page
sPage. If sPage is an empty string, the list is not shown. Unlike CheckSiege and
UnregisterSiege, in this build the function works.
Signature
ViewSiegeList( CSharedCreatureData c, string sPage )Parameters
c (CSharedCreatureData) — the player who is shown the siege list.
sPage (string) — the name of the HTML page of the siege-list window; an empty string is not accepted (the list will not be shown).
Example (illustrative):
ViewSiegeList( talker, "" );Fortress_GetStateNPC🟢 high
Returns the code of the current state of the fortress nFortressId (the ownership/contract stage). By this code
fortress scripts branch their logic: for example, by comparison with 0 they distinguish an unowned fortress from
one occupied by a clan.
Signature
Fortress_GetState( int nFortressId )Parameters
nFortressId (int) — the identifier of the fortress whose state is requestedExample
if ( Fortress_GetState( fortress_id ) == 0 ) {Fortress_GetSiegeStatusNPC🟢 high
Returns the siege-state code of the fortress nFortressId (no siege / siege in progress and its phase). Allows
fortress scripts to understand what stage the siege cycle is in.
Signature
Fortress_GetSiegeStatus( int nFortressId )Parameters
nFortressId (int) — the identifier of the fortress whose siege state is requested
Example (illustrative):
Fortress_GetSiegeStatus( nFortressId );Fortress_PledgeRegisterNPC🟢 high
Registers the player's clan as a contender for the fortress nFortressId (an application for a fortress siege/capture).
The action is initiated by the NPC managing the fortress on behalf of the arriving player.
Signature
Fortress_PledgeRegister( int nNpcId, int nUserId, int nFortressId )
Parameters (per real calls — myself.sm.id, talker.id, fortress_id):
nNpcId (int) — the id of the NPC source of the action (myself.sm.id).
nUserId (int) — the player id (talker.id).
nFortressId (int) — the identifier of the fortress the player's clan is registered for.Example
Fortress_PledgeRegister(myself.sm.id, talker.id, fortress_id);Fortress_BarrackCapturedNPC🟢 high
Reports the capture of a barrack during a fortress siege: marks the barrack nBarrackId of the fortress nFortressId
captured. When all the fortress's barracks are captured, the siege ends in favor of the attackers.
Signature
Fortress_BarrackCaptured( int nNpcId, int nFortressId, int nBarrackId )
Parameters (per real calls — myself.sm.id, fortress_id, barrack_id):
nNpcId (int) — the id of the NPC source of the event (myself.sm.id).
nFortressId (int) — the identifier of the fortress where the barracks are captured.
nBarrackId (int) — the identifier of the captured barracks.Example
Fortress_BarrackCaptured(myself.sm.id, fortress_id, barrack_id);Fortress_ContractCastleNPC🟢 high
Concludes the agreement of the fortress nFortressId with a castle (the fortress's choice of a suzerain castle — a contract). The function is
asynchronous: the result arrives as a separate event (see below). In calls nArg = -1.
Signature
Fortress_ContractCastle( int nNpcId, int nUserId, int nFortressId, int nArg )
Parameters (per real calls — myself.sm.id, talker.id, fortress_id, -1):
nNpcId (int) — the id of the NPC source of the action (myself.sm.id).
nUserId (int) — the player id (talker.id).
nFortressId (int) — the identifier of the fortress concluding the contract.
nArg (int) — the contract parameter (in calls -1).Usage example
if ( reply == 1 ) {
Fortress_ContractCastle( myself.sm.id, talker.id, fortress_id, -1 );
return;
}
Related event: the server's response arrives as the FORTRESS_CONTRACT_CASTLE_RETURNED event (see NASC_HANDLERS).Fortress_OwnerRewardTakenNPC🟢 high
Marks that the owner of the fortress nFortressId took the due periodic reward, and gives
the player the item nItemClassId in the quantity nCount. Protects against re-receiving the owner's
reward.
Signature
Fortress_OwnerRewardTaken( int nNpcId, int nUserId, int nFortressId, int nItemClassId, int64 nCount )
Parameters (per real calls — myself.sm.id, talker.id, fortress_id, item_medal, i0):
nNpcId (int) — the id of the NPC source of the event (myself.sm.id).
nUserId (int) — the id of the owner player (talker.id).
nFortressId (int) — the identifier of the fortress whose reward is received.
nItemClassId (int) — the id of the reward item ([item_pch], e.g. item_medal).
nCount (int64) — the reward quantity.Example
Fortress_OwnerRewardTaken(myself.sm.id, talker.id, fortress_id, item_medal, i0);Agit_GetDecoExpireNPC🟢 high
A getter for clan hall (agit) decorations. By the decoration type nDecoType returns an int — the moment
of expiration of the installed decoration as a timestamp. In scripts this value
is passed to GetDateTime to extract the year/month/day and show the expiration date in a dialog.
Signature
Agit_GetDecoExpire( int nDecoType )Parameters
nDecoType (int) — the agit decoration type. Values (script-convention constants):
1 hpregen · 2 mpregen · 3 cpregen · 6 broadcast · 7 curtain · 8 hanging ·
9 buff · 10 outerflag · 11 platform · 12 itemExample
IntToStr( GetDateTime( Agit_GetDecoExpire( decotype_hpregen ), 1 ) );Agit_GetTeleportLevelNPC🟢 high
Returns the level of the teleport function of this NPC's clan hall (agit): 0 — the function is off,
a higher value — the installed upgrade tier. A pair to Agit_SetTeleportLevel.
Signature
Agit_GetTeleportLevel( )Parameters
(none — the function is called without arguments)Example
Agit_GetTeleportLevel( );Agit_SetTeleportLevelNPC🟢 high
Sets the teleport level of the clan hall (agit). Described in overview, the exact arguments — in
the source tables.
Signature
Agit_SetTeleportLevel( int nLevel )Parameters
nLevel (int) — the level to set for the clan hall's teleport function (0 = off, then the upgrade tiers).
Example (illustrative):
Agit_SetTeleportLevel( nLevel );Agit_StartObserverNPC🟢 high
Sends the player c into observer mode (the siege camera of the clan hall/residence) to the point with
coordinates x, y, z. The position is checked against geodata: with an invalid point observation is not
enabled. If the residence nResidenceId is currently under siege — observation is forbidden (the player
receives a system message). Observation lasts 1 hour (3600 s). It is also blocked if the player
is registered for the Olympiad or has a private store open.
Signature
Agit_StartObserver( CSharedCreatureData c, int x, int y, int z, int nCamParam4, int nCamParam5, int nResidenceId )Parameters
c (CSharedCreatureData) — the player sent into observer mode.
x (int) — the X coordinate of the observation point (checked against geodata).
y (int) — the Y coordinate of the observation point.
z (int) — the Z coordinate of the observation point.
nCamParam4 (int) — an observer camera parameter (passed to the client).
nCamParam5 (int) — an observer camera parameter (passed to the client).
nResidenceId (int) — the residence id: with an active siege observation is forbidden.
Example (illustrative):
Agit_StartObserver( talker, x, y, z, nCamParam4, nCamParam5, nResidenceId );AuctionAgit_GetAgitCostInfoNPC🟢 high
Shows the player c information about the cost of the clan hall (agit) at auction — the price and rental
conditions. Usually called in a manager's dialog after checking that the player is from the owner clan.
Signature
AuctionAgit_GetAgitCostInfo( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature initiating the request for hall cost/auction informationUsage example
if (Castle_GetPledgeId() == talker.pledge_id && talker.pledge_id != 0) {
AuctionAgit_GetAgitCostInfo(talker);
} else {
ShowPage(talker, fnNoAuthority);
}GetDominionSiegeIDNPC🟢 high
Returns the siege id of the territory war (Dominion) to which the creature c belongs — by its
territory. The value is used as a base for computing related ids (in the example, other identifiers
are obtained from it by offsets).
Signature
GetDominionSiegeID( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature by which the territory's siege identifier is determinedUsage example
i0 = GetDominionSiegeID( target );
if ( i0 < 90 ) { i1 = ( i0 + 636 ); } else { i1 = ( i0 + 650 ); }RegisterDominionNPC🟢 high
Registers the creature c's clan as a participant in the territory war (Dominion) for the territory
nDominionId. Usually called by a castle manager and requires lord/clan-leader authority
(in the example IsMyLord and the clan right are checked).
Signature
RegisterDominion( int nDominionId, CSharedCreatureData c )Parameters
nDominionId (int) — the identifier of the territory/residence (Dominion) for registering participation (in calls dominion_id).
c (CSharedCreatureData) — the initiator creature (a player or a clan representative).Usage example
if (IsMyLord(talker) || (HavePledgePower(talker, 18) && Castle_GetPledgeId() == talker.pledge_id && talker.pledge_id != 0)) {
RegisterDominion(dominion_id, talker);
} else {
ShowPage(talker, fnNoAuthority);
}CancelPledgeDominionNPC🟢 high
Cancels the creature c's clan's registration in the territory war (Dominion) for the territory
nDominionId — the reverse action to RegisterDominion.
Signature
CancelPledgeDominion( int nDominionId, CSharedCreatureData c )Parameters
nDominionId (int) — the identifier of the territory/residence (Dominion) whose participation is cancelled.
c (CSharedCreatureData) — the initiator creature (a player or a clan representative).
Example (illustrative):
CancelPledgeDominion( nDominionId, talker );IsDominionOfLordNPC🟢 high
Reports whether the territory (Dominion) nDominionId has an owning lord: 0 — the territory is unclaimed,
a value > 0 — the territory has an owner. Territory identifiers lie in the 80+ range
(in the examples 87, 80+i0).
Signature
IsDominionOfLord( int nDominionId )Parameters
nDominionId (int) — the identifier of the territory/residence (Dominion) checked for belonging to a lord (in calls 87).Usage example
if (IsDominionOfLord(87) == 0) {
ShowQuestPage( talker, "chamberlain_alfred_q0715_01.htm", @path_of_feudal_lord_godard );
} else {
ShowQuestPage( talker, "chamberlain_alfred_q0715_03.htm", @path_of_feudal_lord_godard );
}IsHostileInDominionSiegeNPC🟢 high
Reports whether the creature c is a hostile participant in the current territory-war (Dominion) siege
— an opponent relative to the defending side. Returns 1 (@TRUE) if c
is hostile, otherwise 0.
Signature
IsHostileInDominionSiege( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature checked for hostility in the territory siege
Example (illustrative):
IsHostileInDominionSiege( talker );Residence_GetTaxRateNPC🟢 high
Returns the tax rate of this NPC's residence that will take effect in the next cycle
(in dialogs substituted into the "next_tax_rate" field). No arguments — by the NPC's own residence.
A pair to Residence_GetTaxRateCurrent (the active rate).
Signature
Residence_GetTaxRate( )Parameters
(none — the function is called without arguments)Example
FHTML_SetInt(fhtml0, "next_tax_rate", Residence_GetTaxRate());Residence_GetTaxRateCurrentNPC🟢 high
Returns the currently active tax rate of this NPC's residence (in dialogs substituted
into the "current_tax_rate" field). No arguments — by the NPC's own residence. A pair to Residence_GetTaxRate
(the next cycle's rate).
Signature
Residence_GetTaxRateCurrent( )Parameters
(none — the function is called without arguments)Example
Residence_GetTaxRateCurrent( );Residence_GetTaxIncomeNPC🟢 high
Returns the accumulated tax adena of this NPC's residence (no arguments — by the NPC's own
residence). The value is 64-bit (read from the residence data), so there is no overflow.
The paired Residence_GetTaxIncomeReserved returns the reserved (not yet paid out) part.
Signature
Residence_GetTaxIncome( )Parameters
(none — the function is called without arguments)Example
Residence_GetTaxIncome( );Residence_VaultSaveMoneyNPC🟢 high
Deposits nAmount adena from the player c's inventory into the treasury (income) of this NPC's residence. Requires
the player to have at least nAmount adena — otherwise the deposit does not happen. Usually called
by a manager and requires authority (in the example — the @ppTaxVault right or lord status).
Signature
Residence_VaultSaveMoney( CSharedCreatureData c, int nAmount )Parameters
c (CSharedCreatureData) — the creature initiating the treasury replenishment.
nAmount (int) — the treasury replenishment amount for the residence (adena; in calls reply).Usage example
if ( IsMyLord( talker ) || ( HavePledgePower( talker, @ppTaxVault ) && Castle_GetPledgeId( ) == talker.pledge_id && talker.pledge_id != 0 ) ) {
Residence_VaultSaveMoney( talker, reply );
ShowPage( talker, fnHi );
} else {
ShowPage( talker, fnNoAuthority );
}Residence_TakeOutMoneyNPC🟡 medium
Withdraws funds from the residence treasury — the operation reverse to Residence_VaultSaveMoney (in which
the player deposits adena into the treasury). The meaning is clear, but the function itself cannot be found either in the signature
references, or in the engine sources, or in L2NPC (neither CT2.3 nor CT2.6) — possibly, in these builds it
is absent or is named differently, so the argument list is not confirmed.
Example (illustrative):
Residence_TakeOutMoney( ... );
RemoveResidenceNPC🟢 high
Disbands the residence nResidenceId — resets its clan affiliation (a service
action of the manager). c — the initiator creature.
Signature
RemoveResidence( CSharedCreatureData c, int nResidenceId )Parameters
c (CSharedCreatureData) — the creature initiating the residence removal
nResidenceId (int) — the identifier of the residence being removed
Example (illustrative):
RemoveResidence( talker, nResidenceId );AssignResidenceNpcToPledgeNPC🟢 high
Binds the residence NPC of residence_id to the creature c's clan — transfers the residence's
managing/service NPCs into the clan's ownership. A service action on a change of residence owner.
Signature
AssignResidenceNpcToPledge( int residence_id, CSharedCreatureData c )Parameters
residence_id (int) — the identifier of the residence whose NPC is bound
c (CSharedCreatureData) — the creature/clan to which the residence NPC is bound
Example (illustrative):
AssignResidenceNpcToPledge( residence_id, talker );RegisterUserResurrectionTowerNPC🟢 high
Registers a player at a resurrection tower for tracking potentially
resurrectable ones. Takes the user identifier (user_id); returns
nothing.
Signature
RegisterUserResurrectionTower( int nUserId )Parameters
nUserId (int) — the user identifier (user_id) registered at the resurrection tower (in calls myself.sm.id).Example
RegisterUserResurrectionTower( myself.sm.id );
Related event: the server's response arrives as the REGISTER_USER_RESURRECTION_TOWER_RESULT event (see NASC_HANDLERS).RegisterResurrectionTowerNPC🟢 high
Registers the resurrection tower itself in the system and binds it to a zone. Takes the
tower identifier and the zone identifier; returns nothing.
Signature
RegisterResurrectionTower( int nTowerId, int nZoneId )Parameters
nTowerId (int) — the resurrection tower identifier (in calls myself.i_ai0).
nZoneId (int) — the identifier of the zone the tower is bound to (in calls myself.i_ai1).Example
RegisterResurrectionTower( myself.i_ai0, myself.i_ai1 );
Related event: the server's response arrives as the REGISTER_RESURRECTION_TOWER_RESULT event (see NASC_HANDLERS).Fortresses, clan halls, dominion (Fortress / Agit / Dominion)
30 functionsFortress_GetContractStatusGLOBAL🟢 high
A getter (gg). By the fortress id nFortId returns an int — the status of its contract (for fortresses with id 101…111).
Signature
Fortress_GetContractStatus( int nFortressId )Parameters
nFortressId (int) — the identifier of the fortress whose contract state is requestedExample
if (Fortress_GetContractStatus(fortress_id) != @FORTRESS_CONTRACT_CASTLE)Usage example
if ( Fortress_GetContractStatus( fortress_id ) != 0 ) {
return;
}Fortress_GetAvailableOwnMinutesGLOBAL🟢 high
A getter (gg). By the fortress id nFortId returns an int — how many minutes the current owner has left.
Signature
Fortress_GetAvailableOwnMinutes( int nFortressId )Parameters
nFortressId (int) — the identifier of the fortress whose available ownership time is returnedExample
if ( Fortress_GetAvailableOwnMinutes( fortress_id ) <= 120 && Fortress_GetOwnerPledgeId( fortress_id ) > 0 ) {Usage example
if ( Fortress_GetAvailableOwnMinutes( fortress_id ) <= 120 && Fortress_GetOwnerPledgeId( fortress_id ) > 0 ) {
ShowPage( talker, fnHi6 );
return;
}Fortress_GetNextRewardRemainTimeGLOBAL🟢 high
A getter (gg). By the fortress id nFortId returns an int — the time remaining until the next reward payout to the fortress owner.
Signature
Fortress_GetNextRewardRemainTime( int nFortressId )Parameters
nFortressId (int) — the identifier of the fortress whose time until the next reward is returnedExample
i7 = Fortress_GetNextRewardRemainTime( fortress_id );Castle_GetDomainFortressContractStatusGLOBAL🟢 high
A getter (gg). By the fortress id nFortId returns an int — the status of its contract in the castle's domains.
Signature
Castle_GetDomainFortressContractStatus( int nFortId )Parameters
nFortId (int) — the id of the fortress for which the contract status in the castle's domains is requestedExample
if ( Castle_GetDomainFortressContractStatus( fortress_id ) == 0 ) {Usage example
if ( Castle_GetDomainFortressContractStatus( fortress_id ) == 0 ) {
ShowPage( talker, fnNoCastleContract );
return;
}GetDominionWarStateGLOBAL🟢 high
A getter (gg). By the domain id nDominionId (@*_dominion or 81…89) returns an int — the state of the war for the domain; a value of 5 means the war is on.
Signature
GetDominionWarState( int nDominionId )Parameters
nDominionId (int) — the identifier of the territory/residence (Dominion) whose war state is requestedExample
if (Castle_IsUnderSiege() == @TRUE || GetDominionWarState(dominion_id) == 5)Usage example
if ( Castle_IsUnderSiege( ) == @FALSE && GetDominionWarState( i0 ) != 5 ) {
ShowPage(talker, "mass_teleporter_instant.htm");
return;
}Fortress_GetPledgeSiegeStateNPC🟢 high
Fortress getter (CNPC). Given creature c, returns int — the siege state for its clan; a value of 2 means the creature's clan is currently under siege.
Signature
Fortress_GetPledgeSiegeState( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) whose clan's fortress siege state is checkedExample
if (Fortress_GetPledgeSiegeState(creature) == 2 || (IsNullCreature(creature.master) == @FALSE && Fortress_GetPledgeSiegeState(creature.master) == 2))Usage example
if ( ( Fortress_GetPledgeSiegeState( creature ) == 2 ) || ( IsNullCreature( creature.master ) == 0 && Fortress_GetPledgeSiegeState( creature.master ) == 2 ) ) {
return;
}Fortress_SetFacilityNPC🟢 high
Fortress method (CNPC). For creature c, sets level nLevel of the facility of type nFacilityType (a @FORTRESS_* constant or 0..4).
Signature
Fortress_SetFacility( CSharedCreatureData cCreature, int nFacilityType, int nValue )Parameters
cCreature (CSharedCreatureData) — creature initiating the setting (usually talker).
nFacilityType (int) — type of the fort facility being configured, @FORTRESS_*:
0 GUARD_REINFORCEMENT · 1 GUARD_POWER_UP · 2 DOOR_POWER_UP · 3 PHOTOCANNON · 4 SCOUT
nValue (int) — the facility level/value being set.Example
Fortress_SetFacility(talker, @FORTRESS_PHOTOCANNON, 1);Usage example
if ( OwnItemCount( talker, @adena ) >= i0 ) {
Fortress_SetFacility( talker, 1, 0 );
} else {
ShowPage( talker, "fortress_not_enough_money.htm" );
}Fortress_ResetFacilityNPC🟢 high
Fortress method (CNPC). Resets all facilities of the fortress bound to creature c.
Signature
Fortress_ResetFacility( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature initiating the fort facility resetExample
Fortress_ResetFacility( talker );Usage example
if ( OwnItemCount( talker, @adena ) >= i0 ) {
Fortress_ResetFacility( talker );
} else {
ShowPage( talker, "fortress_not_enough_money.htm" );
}Fortress_IsInBoundaryNPC🟢 high
Fortress predicate (CNPC). Given fortress id nFortId, returns int (1/0) — whether the NPC is within its boundaries.
Signature
Fortress_IsInBoundary( int nFortId )Parameters
nFortId (int) — id of the fortress whose boundaries the NPC is checked against.Example
i8 = fortress_dependancy + Fortress_IsInBoundary(i0);Fortress_GetCastleTreasureLevelNPC🟢 high
Fortress getter (CNPC). Given fortress id nFortId, returns int — the treasury level of the castle the fortress is subordinate to.
Signature
Fortress_GetCastleTreasureLevel( int nFortId )Parameters
nFortId (int) — id of the fortress for which the owning castle's treasury level is taken.Example
i0 = Fortress_GetCastleTreasureLevel( fortress_id );Fortress_CastleTreasureTakenNPC🟢 high
Fortress method (CNPC). Records the fact that the fortress treasury has been taken. Arguments: nNpcId — NPC id, nTalkerId — player id, nFortId — fortress id.
Signature
Fortress_CastleTreasureTaken( int nNpcId, int nUserId, int nFortressId )
Parameters (per real calls — myself.sm.id, talker.id, fortress_id):
nNpcId (int) — id of the NPC originating the event (myself.sm.id).
nUserId (int) — id of the player who took the treasury (talker.id).
nFortressId (int) — identifier of the fort where the treasury was seized.Example
Fortress_CastleTreasureTaken( myself.sm.id, talker.id, fortress_id );Usage example
if ( i0 > 0 ) {
Fortress_CastleTreasureTaken( myself.sm.id, talker.id, fortress_id );
ShowPage( talker, fnGetTreasureSuccess );
}Fortress_ProtectedNpcDiedNPC🟢 high
Fortress method (CNPC). Notifies the system about the death of a protected fortress NPC. Arguments: nNpcId — NPC id, nFortId — fortress id.
Signature
Fortress_ProtectedNpcDied( int nNpcId, int nFortressId )
Parameters (per real calls — myself.sm.id, fortress_id):
nNpcId (int) — id of the NPC originating the event (myself.sm.id).
nFortressId (int) — identifier of the fort where the protected NPC died.Example
Fortress_ProtectedNpcDied( myself.sm.id, fortress_id );Fortress_PledgeUnregisterNPC🟢 high
Fortress method (CNPC). Removes the clan's registration for the siege/ownership of a fortress. Arguments: nNpcId — NPC id, nTalkerId — player id, nFortId — fortress id.
Signature
Fortress_PledgeUnregister( int nNpcId, int nUserId, int nFortressId )
Parameters (per real calls — myself.sm.id, talker.id, fortress_id):
nNpcId (int) — id of the NPC originating the action (myself.sm.id).
nUserId (int) — player id (talker.id).
nFortressId (int) — identifier of the fort the registration is removed from.Example
Fortress_PledgeUnregister( myself.sm.id, talker.id, fortress_id );Usage example
if ( reply == 0 ) {
Fortress_PledgeUnregister( myself.sm.id, talker.id, fortress_id );
} else {
if ( reply == 2 ) {
ShowMultisell( 614, talker );
}
}Fortress_GetOwnerRewardCycleCountNPC🟢 high
Fortress getter (CNPC). Given fortress id nFortId, returns int — how many reward cycles its owner has already received.
Signature
Fortress_GetOwnerRewardCycleCount( int nFortId )Parameters
nFortId (int) — id of the fortress for which the owner's received reward cycles are counted.Example
i0 = Fortress_GetOwnerRewardCycleCount( fortress_id );Agit_GetDecoLevelNPC🟢 high
Clan hall decoration getter (CNPC). Given decoration type nDecoType (@decotype_*), returns int — its current level; a value greater than 0 means the decoration is installed.
Signature
Agit_GetDecoLevel( int nDecoType )Parameters
nDecoType (int) — agit decoration type. Values (script-convention constants):
1 hpregen · 2 mpregen · 3 cpregen · 6 broadcast · 7 curtain · 8 hanging ·
9 buff · 10 outerflag · 11 platform · 12 itemExample
if ( Agit_GetDecoLevel( decotype_buff ) > 0 ) {Usage example
if ( Agit_GetDecoLevel( decotype_item ) == 0 ) {
ShowPage( talker, fnFuncDisabled );
}Agit_GetDecoFeeNPC🟢 high
Decoration getter (CNPC). Given type nDecoType and level nLevel, returns int — the fee for installing/renewing a decoration of that level.
Signature
Agit_GetDecoFee( int nDecoType, int nLevel )Parameters
nDecoType (int) — agit decoration type. Values (script-convention constants):
1 hpregen · 2 mpregen · 3 cpregen · 6 broadcast · 7 curtain · 8 hanging ·
9 buff · 10 outerflag · 11 platform · 12 item
nLevel (int) — decoration level (usually Agit_GetDecoLevel(nDecoType)).Example
FHTML_SetStr( fhtml0, "HP" + "Cost", "(" + MakeFString( 6, IntToStr( Agit_GetDecoFee( decotype_hpregen, Agit_GetDecoLevel( decotype_hpregen ) ) ), IntToStr( Agit_GetDecoDay( decotype_hpregen, Agit_GetDecoLevel( decotype_hpregen ) ) ), _blank, _blank, _blank ) + ")" );Agit_GetDecoDayNPC🟢 high
Decoration getter (CNPC). Given type nDecoType and level nLevel, returns int — the decoration's duration in days.
Signature
Agit_GetDecoDay( int nDecoType, int nLevel )Parameters
nDecoType (int) — agit decoration type. Values (script-convention constants):
1 hpregen · 2 mpregen · 3 cpregen · 6 broadcast · 7 curtain · 8 hanging ·
9 buff · 10 outerflag · 11 platform · 12 item
nLevel (int) — decoration level (usually Agit_GetDecoLevel(nDecoType)).Example
FHTML_SetStr( fhtml0, "HP" + "Cost", "(" + MakeFString( 6, IntToStr( Agit_GetDecoFee( decotype_hpregen, Agit_GetDecoLevel( decotype_hpregen ) ) ), IntToStr( Agit_GetDecoDay( decotype_hpregen, Agit_GetDecoLevel( decotype_hpregen ) ) ), _blank, _blank, _blank ) + ")" );Agit_GetCostFailDayNPC🟢 high
Decoration getter (CNPC), no arguments. Returns int — the allowed number of days of overdue payment after which the decoration is lost.
Signature
Agit_GetCostFailDay( )Parameters
(none — the function is called without arguments)Example
if ( Agit_GetCostFailDay( ) == 0 ) {Usage example
if ( Agit_GetCostFailDay( ) == 0 ) {
ShowPage( talker, fnHi );
} else {
FHTML_SetFileName( fhtml0, fnCostFail );
FHTML_SetInt( fhtml0, "CostFailDayLeft", ( 8 - Agit_GetCostFailDay( ) ) );
ShowFHTML( talker, fhtml0 );
}Agit_GetDecoIdNPC🟢 high
Decoration getter (CNPC). Given decoration type nDecoType, returns int — its internal id.
Signature
Agit_GetDecoId( int nDecoType )Parameters
nDecoType (int) — agit decoration type. Values (script-convention constants):
1 hpregen · 2 mpregen · 3 cpregen · 6 broadcast · 7 curtain · 8 hanging ·
9 buff · 10 outerflag · 11 platform · 12 item
Example: no direct calls in our scripts.Agit_SetDecoNPC🟢 high
Decoration method (CNPC). For creature c, installs or updates the decoration of type nDecoType to level nLevel.
Signature
Agit_SetDeco( CSharedCreatureData cCreature, int nDecoType, int nLevel )Parameters
cCreature (CSharedCreatureData) — creature initiating the clan hall decoration setting.
nDecoType (int) — agit decoration type. Values (script-convention constants):
1 hpregen · 2 mpregen · 3 cpregen · 6 broadcast · 7 curtain · 8 hanging ·
9 buff · 10 outerflag · 11 platform · 12 item
nLevel (int) — the decoration level being set.Example
Agit_SetDeco( talker, i0, i1 );Agit_ResetDecoNPC🟢 high
Decoration method (CNPC). For creature c, resets the decoration of type nDecoType.
Signature
Agit_ResetDeco( CSharedCreatureData cCreature, int nDecoType )Parameters
cCreature (CSharedCreatureData) — creature whose clan hall decoration is reset (talker).
nDecoType (int) — type of the agit decoration to reset; in calls = FloatToInt(reply/1000).
Values (script-convention constants):
1 hpregen · 2 mpregen · 3 cpregen · 6 broadcast · 7 curtain · 8 hanging ·
9 buff · 10 outerflag · 11 platform · 12 itemExample
Agit_ResetDeco( talker, i0 );DeclareLordNPC🟢 high
Method (CNPC). Declares creature c the lord of dominion nDominionId.
Signature
DeclareLord( int nDominionId, CSharedCreatureData c )Parameters
nDominionId (int) — id of the dominion for which the lord is declared.
c (CSharedCreatureData) — creature (player) being declared lord of the dominion.Example
DeclareLord(dominion_id, talker);IsLordOfCastleNPC🟢 high
Predicate (CNPC). Given creature c, returns int (1/0) — whether the player is the lord of a castle/dominion.
Signature
IsLordOfCastle( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) checked for castle/dominion lord statusExample
i0 = IsLordOfCastle( talker );
i1 = IsLordOfCastle(talker);CancleUserDominionNPC🟢 high
Method (CNPC). Withdraws creature c's participation in the war for dominion nDominionId.
Signature
CancleUserDominion( int nDominionId, CSharedCreatureData c )Parameters
nDominionId (int) — id of the dominion from whose war the participant is withdrawn.
c (CSharedCreatureData) — creature (player) whose war participation is withdrawn.
Example: no direct calls in our scripts.Residence_GetTaxIncomeReservedNPC🟢 high
Residence getter (CNPC), no arguments. Returns int64 — the reserved (not yet paid out) tax income.
Signature
Residence_GetTaxIncomeReserved( )Parameters
(none — the function is called without arguments)Example
FHTML_SetInt( fhtml0, "tax_income_reserved", Residence_GetTaxIncomeReserved( ) );Residence_SetTaxRateNPC🟢 high
Residence method (CNPC). Sets the residence tax rate nRate.
Signature
Residence_SetTaxRate( int nTaxRate )Parameters
nTaxRate (int) — the residence tax rate being set, in percent (in calls 0 or reply).Example
Residence_SetTaxRate( 0 );
Residence_SetTaxRate( reply );Usage example
if ( reply < 0 ) {
Residence_SetTaxRate( 0 );
FHTML_SetInt( fhtml0, "next_tax_rate", 0 );
} else {
Residence_SetTaxRate( reply );
FHTML_SetInt( fhtml0, "next_tax_rate", reply );
}Residence_VaultTakeOutMoneyNPC🟢 high
Residence method (CNPC). Gives creature c the amount nAmount from the residence treasury; returns int.
Signature
Residence_VaultTakeOutMoney( CSharedCreatureData c, int nAmount )Parameters
c (CSharedCreatureData) — creature (player) who receives the money from the treasury.
nAmount (int) — amount to give out (adena; in calls reply).Example
Residence_VaultTakeOutMoney( talker, reply );GetControlTowerLevelNPC🟢 high
Method (CNPC). Given creature c and zone name sZoneName, reports the level of that zone's control tower (return type not confirmed).
Signature
GetControlTowerLevel( CSharedCreatureData c, string sZoneName )Parameters
c (CSharedCreatureData) — creature that will receive the result (via the CONTROLTOWER_LEVEL_INFORMED event).
sZoneName (string) — name of the zone whose control tower is queried.Example
GetControlTowerLevel( talker, dmgzonename1 );
GetControlTowerLevel( talker, dmgzonename2 );Usage example
if ( GetCookie( talker, "dmgzone_num" ) == 2 ) {
GetControlTowerLevel( talker, dmgzonename2 );
}
Related event: the server's response arrives as the CONTROLTOWER_LEVEL_INFORMED event (see NASC_HANDLERS).SetControlTowerLevelNPC🟢 high
Method (CNPC). For the zone named sZoneName, sets the control tower level nLevel.
Signature
SetControlTowerLevel( string sZoneName, int nLevel )Parameters
sZoneName (string) — name of the zone whose control tower level is set.
nLevel (int) — the control tower level being set.Example
SetControlTowerLevel( dmgzonename1, ( 2 * i1 ) );
SetControlTowerLevel( dmgzonename2, ( 2 * i1 ) );
SetControlTowerLevel(dmgzonename1, 2 * i1);
SetControlTowerLevel(dmgzonename2, 2 * i1);Castle_GetRawSystemTimeNPC🟢 high
Getter (CNPC), no arguments. Returns int — the raw system time, used to synchronize sieges.
Signature
Castle_GetRawSystemTime( )Parameters
(none — the function is called without arguments)Example
if ( ( Castle_GetRawSystemTime( ) - Castle_GetRawSiegeTime( ) ) < 1800 ) {Usage example
if ( _from_choice == 0 || ( HaveMemo( talker, @competition_for_the_bandit_stronghold ) == 1 && OwnItemCount( talker, @q_contest_certificate ) > 0 && OwnItemCount( talker, @q_tarlk_amulet ) < 30 && ( Castle_GetRawSiegeTime( ) - GetMemoState( talker, @competition_for_the_bandit_stronghold ) ) < 86400 && ( Castle_GetRawSiegeTime( ) - Castle_GetRawSystemTime( ) ) > 0 ) ) {
SetCurrentQuestID( @competition_for_the_bandit_stronghold );
ShowPage( talker, "azit_messenger_q0504_07.htm" );
}TERRITORY BATTLES, CLANS, EVENT REGISTRATION AND PREMIUM (TB / Pledge / Register / Premium)
26 functionsGetSubpledgeMasterNameGLOBAL🟢 high
Returns the name of a sub-clan leader as a string. The first argument is a creature
(CSharedCreatureData), the second is the sub-clan ID.
Signature
GetSubpledgeMasterName( CSharedCreatureData cCreature, int nSubPledgeId )Parameters
cCreature (CSharedCreatureData) — the creature (player) in whose clan context the sub-clan is searched
nSubPledgeId (int) — the id of the sub-clan whose leader name is requestedExample
s0 = GetSubpledgeMasterName( talker, reply );Usage example
s0 = GetSubpledgeMasterName( talker, reply );
if ( IsNullString(s0 ) == 1 ) {
s0 = "";
s0 = MakeFString( 1010642, "", "", "", "", "" );
}TB_SetNpcTypeNPC🟢 high
Sets the territory battle participant type (1–5: NPC kinds). Called on a
creature object (CSharedCreatureData), with the type number passed as the second argument;
returns nothing.
Signature
TB_SetNpcType( CSharedCreatureData c, int nType )Parameters
c (CSharedCreatureData) — creature whose territory battle participant type is set.
nType (int) — number of the territory battle participant type being set, 1..5 (in calls 2, 5).Example
TB_SetNpcType( talker, 2 );Usage example
if ( reply == 8 ) {
TB_SetNpcType( talker, 5 );
} else
if ( reply == 9 ) {
TB_GetNpcType( talker );
}
Related event: the server's response arrives as the TB_SET_NPC_TYPE_RETURNED event (see NASC_HANDLERS).TB_GetNpcTypeNPC🟢 high
Gets the current territory battle participant type for the given creature
(CSharedCreatureData). Called on the creature object.
Signature
TB_GetNpcType( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature whose territory battle participant type is queriedExample
TB_GetNpcType( talker );Usage example
if ( reply == 9 ) {
TB_GetNpcType( talker );
}
Related event: the server's response arrives as the TB_GET_NPC_TYPE_INFORMED event (see NASC_HANDLERS).TB_GetPledgeRegisterStatusNPC🟢 high
Checks the registration status of the player's clan in the territory battle; the result arrives via an event.
Per the L2Server handler (NpcQueryTeamBattlePledge → CTeamBattleAgit::GetPledgeRegisterStatusForNpcServer)
the server looks for the player's clan among those registered at the agit (up to 5 slots) and returns the slot index,
or a "not registered" code. The flag affects exactly this code when there is no registration: with
nMode=0 it returns -3, with nMode=1 it stays -1 — scripts use this for different dialog branches.
Signature
TB_GetPledgeRegisterStatus( CSharedCreatureData c, int nMode )Parameters
c (CSharedCreatureData) — creature (player) whose clan's registration is checked.
nMode (int) — response mode for an unregistered clan: 0 → result code -3, 1 → code -1.Example
TB_GetPledgeRegisterStatus( talker, 1 );
TB_GetPledgeRegisterStatus( talker, 0 );Usage example
if ( GetPledgeSkillLevel( talker ) >= 4 ) {
TB_GetPledgeRegisterStatus( talker, 0 );
} else {
ShowPage( talker, "azit_messenger_q0504_04.htm" );
}
Related event: the server's response arrives as the TB_GET_PLEDGE_REGISTER_STATUS_INFORMED event (see NASC_HANDLERS).TB_RegisterPledgeNPC🟢 high
Registers a clan for participation in territory wars. Called on a creature
object (CSharedCreatureData), with no extra arguments.
Signature
TB_RegisterPledge( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) whose clan is registered for territory warsExample
TB_RegisterPledge( talker );
Related event: the server's response arrives as the TB_REGISTER_PLEDGE_RETURNED event (see NASC_HANDLERS).TB_RegisterMemberNPC🟢 high
Registers a clan member as a territory battle participant. Called on a
creature object (CSharedCreatureData) with no extra arguments.
Signature
TB_RegisterMember( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) registered as a territory battle participantExample
TB_RegisterMember( talker );Usage example
if ( talker.is_pledge_master != 1 ) {
TB_RegisterMember( talker );
} else {
ShowPage( talker, "farm_kel_mahum_messenger_5.htm" );
}
Related event: the server's response arrives as the TB_REGISTER_MEMBER_RETURNED event (see NASC_HANDLERS).TB_CheckMemberRegisterStatusNPC🟢 high
Checks a clan member's registration in the territory battle. The first argument is the
event/agit ID, the second is a creature (CSharedCreatureData).
Signature
TB_CheckMemberRegisterStatus( int nAgitId, CSharedCreatureData c )Parameters
nAgitId (int) — id of the event/agit within which the registration is checked (in calls AgitID).
c (CSharedCreatureData) — creature (player) whose clan member registration is checked.Example
TB_CheckMemberRegisterStatus( AgitID, talker );Usage example
if ( myself.i_ai1 == 0 ) {
TB_CheckMemberRegisterStatus( AgitID, talker );
} else {
ShowPage( talker, "agit_mass_teleporter001.htm" );
}TB_GetBattleRoyalPledgeListNPC🟢 high
Returns the list of clans participating in territory battles. Called on a
creature object (CSharedCreatureData).
Signature
TB_GetBattleRoyalPledgeList( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature in whose context the participant clan list is requestedExample
TB_GetBattleRoyalPledgeList( talker );Usage example
if ( ask == 101 ) {
TB_GetBattleRoyalPledgeList( talker );
}
Related event: the server's response arrives as the TB_GET_BATTLE_ROYAL_PLEDGE_LIST_INFORMED event (see NASC_HANDLERS).UpdatePledgeNameValueNPC🟢 high
Changes the clan's reputation by the given number (negative decreases it).
Called on a creature object (CSharedCreatureData); returns the new reputation
value.
Signature
UpdatePledgeNameValue( CSharedCreatureData c, int nDelta )Parameters
c (CSharedCreatureData) — creature (player) whose clan's reputation is changed.
nDelta (int) — signed amount of the reputation change (negative decreases; in calls -10000, i0).Example
UpdatePledgeNameValue( talker, -10000 );Usage example
if ( i0 > 0 ) {
UpdatePledgeNameValue( talker, i0 );
}OwnPledgeNameValueNPC🟢 high
Returns the current clan reputation of the talker (CSharedCreatureData) as an integer.
Signature
OwnPledgeNameValue( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (talker) whose clan reputation is queriedExample
if ( OwnPledgeNameValue( talker ) >= 10000 ) {Usage example
if ( OwnPledgeNameValue( talker) >= 5000 ) {
UpdatePledgeNameValue( talker, -5000 );
CreateSubPledge( talker, i0, i1, s0 );
} else {
ShowPage( talker, "pl_err_fame.htm" );
}GetPledgeByIndexNPC🟢 high
Gets a clan data object (CSharedPledgeData) by a numeric index.
Signature
GetPledgeByIndex( int nIndex )Parameters
nIndex (int) — numeric index of the clan whose data is taken.Example
pledge0 = GetPledgeByIndex( i0 );Usage example
pledge0 = GetPledgeByIndex( i0 );
if ( IsNull( pledge0 ) == 0 ) {
FHTML_SetStr( fhtml0, "pledge0", pledge0.name );
FHTML_SetStr( fhtml0, "p_member_count0", IntToStr( i1 ) );
}GetPledgeCastleSiegeDefenceCountNPC🟢 high
Returns the number of the clan's defense attempts in a castle siege. Argument — a creature
(CSharedCreatureData), return — an integer.
Signature
GetPledgeCastleSiegeDefenceCount( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) whose clan's siege defense attempts are countedExample
i0 = GetPledgeCastleSiegeDefenceCount(talker);RegisterToEventListenerNPC🟢 high
Subscribes this NPC to global events. Per the L2NPC decompile
(CNPC::RegisterToEventListener_48F6DC) the engine registers the NPC in the shared
GlobalEventListener registry by event type. In the compiled scripts only the value 1 is used
(per the call context ssq_event_listener == 1 — subscription to Seven Signs events).
Signature
RegisterToEventListener( int nEventType )Parameters
nEventType (int) — global event type to subscribe to (registered in GlobalEventListener;
in calls 1 — per context, the SSQ / Seven Signs event).Example
RegisterToEventListener( 1 );Usage example
if ( ssq_event_listener == 1 ) {
RegisterToEventListener( 1 );
}AddPremiumPointsNPC🟢 high
Adds premium points to a player. First argument — a creature (CSharedCreatureData),
second — the number of points (int64); returns nothing.
Signature
AddPremiumPoints( CSharedCreatureData cCreature, int64 points )Parameters
cCreature (CSharedCreatureData) — creature (player) who is granted the premium points
points (int64) — number of premium points to addExample
AddPremiumPoints( talker, ( i7 * 3 ) );IsUserPremiumNPC🟢 high
Returns 1 if the player has an active premium subscription. Argument — a creature
(CSharedCreatureData).
Signature
IsUserPremium( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) whose active premium subscription is checkedExample
if (IsUserPremium(talker) == @FALSE)Usage example
if ( IsUserPremium( talker ) == @FALSE ) {
ShowPage( talker, "npc_rim_maker001e.htm" );
return;
}GetPremiumLevelNPC🟢 high
Returns the player's premium level (0 — none, 1 and above — the level). Argument —
a creature (CSharedCreatureData).
Signature
GetPremiumLevel( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) whose premium level is queriedExample
if (GetPremiumLevel(talker) == 2) {Usage example
if (GetPremiumLevel(talker) < 2) {
ShowPage(talker, "not_enoth_vip_lvl.htm");
}SetUserPremiumNPC🟢 high
Activates or extends the player's premium subscription. Arguments: a creature
(CSharedCreatureData), duration in seconds, two integer parameters and
a string parameter; returns nothing.
Signature
SetUserPremium( CSharedCreatureData cCreature, int nDuration, int nParam1, int nParam2, string pwsParam3 )Parameters
cCreature (CSharedCreatureData) — creature (player) whose premium is activated/extended
nDuration (int) — subscription duration in seconds
nParam1 (int) — additional integer subscription parameter
nParam2 (int) — additional integer subscription parameter
pwsParam3 (string) — additional string subscription parameterExample
SetUserPremium( talker, ( i4 * 86400 ), 1, 1, "" );Usage example
if ( IsUserPremium( talker ) == 0 ) {
SetUserPremium( talker, ( 30 * 86400 ), 1, 1, "" );
ShowPage( talker, "obtshop_premium_ok.htm" );
} else {
ShowPage( talker, "obtshop_premium_already.htm" );
}ShowPremiumItemListNPC🟢 high
Shows the player a window with premium goods. Argument — a creature
(CSharedCreatureData).
Signature
ShowPremiumItemList( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) shown the premium goods windowExample
ShowPremiumItemList(talker);Usage example
if (reply == 1) {
ShowPremiumItemList(talker);
}IsMidWarMemberNPC🟢 high
Returns 1 if the player is a participant in mid wars. Argument —
a creature (CSharedCreatureData).
Signature
IsMidWarMember( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) being checked, whose participation in mid wars is determinedExample
if (MidWarIsEnable == @TRUE && IsMidWarMember(talker) != @FALSE)Usage example
if (MidWarIsEnable == @TRUE && IsMidWarMember(talker) != @FALSE)
{
ShowPage(talker, "midwar_no_epic.htm");
return;
}IsJoinableToDawnNPC🟢 high
Returns 1 if the player can join the Lords of Dawn. Argument —
a creature (CSharedCreatureData).
Signature
IsJoinableToDawn( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) being checked, whose eligibility to join the Lords of Dawn is verifiedExample
if ( IsJoinableToDawn( talker ) ) {Usage example
if ( IsJoinableToDawn( talker ) ) {
ShowPage( talker, szName + "_" + QUEST_ID + "_39a.htm" );
} else {
ShowPage( talker, szName + "_" + QUEST_ID + "_38.htm" );
}CheckCursedUserNPC🟢 high
Checks a player's curse. Argument — a creature (CSharedCreatureData); returns
nothing.
Signature
CheckCursedUser( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — creature (player) being checked for the presence of a curseExample
CheckCursedUser(talker);RegisterFortressEventExMAKER🟢 high
Binds an event to a fortress. Three integer arguments: fortress ID, event ID and
a spawn flag; returns nothing.
Signature
RegisterFortressEventEx( int nFortId, int nEventId, int bSpawn )Parameters
nFortId (int) — id of the fortress the event is bound to.
nEventId (int) — id of the event being bound.
bSpawn (int) — spawn flag (is_spawnN in calls, 0/1).Example
RegisterFortressEventEx( fortress_id, event_id1, is_spawn1 );
RegisterFortressEventEx( fortress_id, event_id2, is_spawn2 );
RegisterFortressEventEx( fortress_id, event_id3, is_spawn3 );
RegisterFortressEventEx( fortress_id, event_id4, is_spawn4 );Usage example
if ( event_id1 > -1 ) {
RegisterFortressEventEx( fortress_id, event_id1, is_spawn1 );
}
Related event: the bound event_id is returned to the maker in the event_id field of the ON_FORTRESS_EVENT event when the fortress reaches the corresponding state (see NASC_HANDLERS).RegisterInstantZoneEventExMAKER🟢 high
Binds an event to an instant zone. Four integer arguments: zone type, cluster
ID, event ID and a flag (0/1); returns nothing.
Signature
RegisterInstantZoneEventEx( int nZoneType, int nClusterId, int nEventId, int nFlag )Parameters
nZoneType (int) — instant zone type.
nClusterId (int) — id of the zone cluster.
nEventId (int) — id of the event being bound.
nFlag (int) — mode flag: 1 — spawn, 0 — despawn (in calls: spawn_event_id=1, despawn_event_id=0).Example
RegisterInstantZoneEventEx( inzone_type_param, inzone_cluster_id, spawn_event_id, 1 );
RegisterInstantZoneEventEx( inzone_type_param, inzone_cluster_id, despawn_event_id, 0 );
RegisterInstantZoneEventEx(inzone_type_param, inzone_cluster_id, olympiad_event_id, 0);Usage example
if ( on_start_spawn == 1 ) {
RegisterInstantZoneEventEx( inzone_type_param, inzone_cluster_id, spawn_event_id, 1 );
}
Related event: the bound event_id is returned to the maker in the event_id field of the ON_INSTANT_ZONE_EVENT event when a zone of the corresponding type spawns/despawns (see NASC_HANDLERS).RegisterAgitSiegeEventExMAKER🟢 high
Registers an agit siege event. The argument is a castle ID; the return value is an integer.
Signature
RegisterAgitSiegeEventEx( int nCastleId )Parameters
nCastleId (int) — id of the castle for which the agit siege event is registered (CastleID in calls).Example
RegisterAgitSiegeEventEx( CastleID );
Related event: subscribes the maker to residence (agit/clan hall) siege events for the specified castle — the siege event family ON_START_SIEGE_EVENT / ON_END_SIEGE_EVENT / ON_PROCLAIM_SIEGE_EVENT / ON_CANCEL_SIEGE_EVENT (see NASC_HANDLERS).RegisterSiegeEventExMAKER🟢 high
Registers a siege event. The argument is a castle or dominion ID; the return value is an
integer.
Signature
RegisterSiegeEventEx( int nCastleOrDominionId )Parameters
nCastleOrDominionId (int) — id of the castle or dominion for which the siege event is registered (CastleID / dominion_id in calls).Example
RegisterSiegeEventEx(dominion_id);
RegisterSiegeEventEx(CastleID);
Related event: subscribes the maker to castle siege events — ON_START_SIEGE_EVENT, ON_END_SIEGE_EVENT, ON_PROCLAIM_SIEGE_EVENT, ON_CANCEL_SIEGE_EVENT; for a dominion — DOMINION_SIEGE_START, DOMINION_SIEGE_END, ON_DECLARE_DOMINION_EVENT (see NASC_HANDLERS).RegisterNpcPosEventMAKER🟢 high
Registers an event by name; bound to the NPC's position. The argument is a string with
the event name; the return value is an integer.
Signature
RegisterNpcPosEvent( string sEventName )Parameters
sEventName (string) — name of the event bound to the NPC's position.Example
RegisterNpcPosEvent( EventName );SEVEN SIGNS (Seven Signs, SSQ)
18 functionsGetSSQPartGLOBAL🟢 high
Available on CNPC (myself) or globally (gg), takes a creature [CSharedCreatureData]. Reports which side the player is on: none, Dusk, or Dawn. The return is the side scale from [manual_pch] (none 0, Dusk 1, Dawn 2).
Signature
GetSSQPart( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose side (none/Dusk/Dawn) is requestedExample
if ( GetSSQPart( c0 ) == 0 ) {Usage example
if ( GetSSQPart( talker ) != 0 ) {
ShowMultisell( reply, talker );
}GetSSQStatusNPC🟢 high
Available on CNPC (myself) and CGlobalObject (gg), no arguments. Returns the current event phase from [manual_pch]: the collection period (side competition, 1), the tallying period (2), or the seal validity period (winner bonuses, 3). This is the main gate of all NPC SSQ logic; almost everything else is wrapped in it.
Signature
GetSSQStatus( )Parameters
(none — the function is called without arguments)Example
if (GetSSQStatus() == 3) {Usage example
if ( GetSSQStatus( ) == 3 && GetSSQPart( talker ) != 2 ) {
ShowPage( talker, szName + "083.htm" );
}GetSSQWinnerNPC🟢 high
Available on CNPC (myself) or globally (gg), no arguments. Returns the winning side of the current event cycle. The return value uses the same side scale as the player's side lookup.
Signature
GetSSQWinner( )Parameters
(none — the function is called without arguments)Example
if ( GetSSQWinner( ) == 1 ) {Usage example
if ( GetSSQPart( talker ) != GetSSQWinner( ) ) {
return;
}GetSSQSealOwnerNPC🟢 high
Available on CNPC (myself) or globally (gg), takes the seal number nSeal from [manual_pch]. Returns which side owns a specific seal; there are seven seals, each with its own name constant. The return value uses the same side scale (none, Dusk, Dawn).
Signature
GetSSQSealOwner( int nSeal )Parameters
nSeal (int) — seal number (manual_pch): 1 = Avarice, 2 = Revelation,
3 = Strife. Return — the owning side: 0 = tie/nobody, 1 = Dusk, 2 = Dawn.Example
i0 = GetSSQSealOwner(SSQLoserTeleport);
i1 = GetSSQSealOwner( SSQLoserTeleport );Usage example
if ( GetSSQSealOwner( 1 ) == 1 ) {
BroadcastSystemMessage( myself.sm, 0, 1215 );
}GetTimeOfSSQNPC🟢 high
Available on CNPC (myself). Returns the timestamp of one of the Seven Signs period boundaries (in the same Unix seconds as GetTimeOfDay). The argument is a field index from 0 to 3: the engine stores four boundary timestamps of the event (e.g. start and end of collection, seal check, end of season), and nArg selects the needed one; any other value returns zero. The typical use is to compute how long remains until the end of the period: subtract the current time GetTimeOfDay() from the result.
Signature
GetTimeOfSSQ( int nIndex )Parameters
nIndex (int) — index of the SSQ period boundary timestamp, 0..3 (the engine stores 4 timestamps; any other value → 0).Example
i1 = GetTimeOfSSQ(1) - GetTimeOfDay();Usage example
if ( ( ( ( i0 >= 0 && i0 < 18 ) || ( i0 >= 20 && i0 < 38 ) ) || ( i0 >= 40 && i0 < 58 ) ) || ( GetTimeOfSSQ( 1 ) - GetTimeOfDay( ) ) <= 120 ) {
ShowPage( talker, "ssq_main_event_acolyte_q0505_22.htm" );
RemoveMemo( talker, @blood_offering );
return;
}AddSSQMemberNPC🟢 high
Registers a player with the chosen Seven Signs (SSQ) side, specifying the seal and the points to award.
Returns 1 if the registration was accepted, and 0 if no player was passed. The awarded points are 64-bit.
Signature
AddSSQMember( CSharedCreatureData cCreature, int nPart, int nType, int nSeal, int64 nPoints, int nArg5 )Parameters
cCreature (CSharedCreatureData) — the player being registered with the SSQ side.
nPart (int) — SSQ side: 1 = Dusk, 2 = Dawn.
nType (int) — registration type (participant role); = 1 in the calls.
nSeal (int) — chosen seal: 1 = Avarice, 2 = Revelation, 3 = Strife.
nPoints (int64) — points awarded on registration.
nArg5 (int) — additional participant registration parameter.Example
if (AddSSQMember(talker, 2, 1, 2, i3, i4) == 0) {Usage example
if ( AddSSQMember( talker, 2, 1, 2, i3, i4 ) == 0 ) {
return;
}GetDepositedSSQItemCountNPC🟢 high
Available on CNPC (myself), takes a creature [CSharedCreatureData], the side nPart and the item type nType. Returns how many items (seals/symbols) the player has deposited. The side and type are passed as numbers; the exact semantics of some arguments are inferred from the calls.
Signature
GetDepositedSSQItemCount( CSharedCreatureData cCreature, int nPart, int nType )Parameters
cCreature (CSharedCreatureData) — the player whose deposited items are counted.
nPart (int) — SSQ side: 1 = Dusk, 2 = Dawn.
nType (int) — category of the deposited item: observed values are 0 and 1 (two categories of seals/symbols).Example
i0 = GetDepositedSSQItemCount( talker, 2, 0 );DepositSSQItemNPC🟢 high
Available on CNPC (myself), takes a creature [CSharedCreatureData], the side nPart, the item type nType, the identifier nId and the count nCount. Deposits an item (seal/symbol) on the player's behalf. The side and type are passed as numbers; the exact semantics of some arguments are inferred from the signature.
Signature
DepositSSQItem( CSharedCreatureData cCreature, int nPart, int nType, int64 nId, int64 nCount )Parameters
cCreature (CSharedCreatureData) — the player on whose behalf the item is deposited.
nPart (int) — SSQ side: 1 = Dusk, 2 = Dawn.
nType (int) — category of the deposited item: 0/1 (two categories of seals/symbols).
nId (int64) — identifier of the deposited item.
nCount (int64) — count of the deposited item.
Example (illustrative):
DepositSSQItem( talker, nPart, nType, nId, nCount );DeleteDepositedSSQItemNPC🟢 high
Available on CNPC (myself), takes a creature [CSharedCreatureData], the side nPart, the item type nType and the count nCount. Writes off previously deposited items. The side and type are passed as numbers; the exact semantics of some arguments are inferred from the calls.
Signature
DeleteDepositedSSQItem( CSharedCreatureData cCreature, int nPart, int nType, int64 nCount )Parameters
cCreature (CSharedCreatureData) — the player whose deposited items are written off
nPart (int) — SSQ side
nType (int) — type of the item being written off (seal/symbol)
nCount (int64) — number of items being written offExample
DeleteDepositedSSQItem(talker, 2, 0, i0);DeleteDepositedSSQItemAndGiveRewardsNPC🟢 high
Writes off nCount of the player's previously deposited Seven Signs items (seals/symbols) and
at the same time gives him the rewards he is entitled to. The side nPart and the item type
nType are set as numbers (see parameters).
Signature
DeleteDepositedSSQItemAndGiveRewards( CSharedCreatureData member, int nPart, int nType, int64 nCount )Parameters
member (CSharedCreatureData) — the player whose deposited items are written off and who receives the rewards
nPart (int) — SSQ side
nType (int) — type of the item being written off (seal/symbol)
nCount (int64) — number of items being written off
Example (illustrative):
DeleteDepositedSSQItemAndGiveRewards( talker, nPart, nType, nCount );GetSSQMemberCountNPC🟢 high
Returns the number of participants registered with the specified Seven Signs (SSQ) side: 1 = Dusk,
2 = Dawn.
Signature
GetSSQMemberCount( int nPart )Parameters
nPart (int) — the SSQ side whose participant count is returned: 1 = Dusk, 2 = Dawn.
Example (illustrative):
GetSSQMemberCount( nPart );GetSSQSealSelectionCountNPC🟢 high
Returns how many participants of the specified Seven Signs side chose the specified seal (see
parameters — sides and seals).
Signature
GetSSQSealSelectionCount( int nPart, int nSeal )Parameters
nPart (int) — SSQ side: 1 = Dusk, 2 = Dawn.
nSeal (int) — seal: 1 = Avarice, 2 = Revelation, 3 = Strife.
Example (illustrative):
GetSSQSealSelectionCount( nPart, nSeal );GetSSQTotalPointNPC🟢 high
Returns the total points of the specified Seven Signs side accumulated in the current cycle: 1 = Dusk,
2 = Dawn.
Signature
GetSSQTotalPoint( int nPart )Parameters
nPart (int) — the SSQ side whose total points are returned: 1 = Dusk, 2 = Dawn.
Example (illustrative):
GetSSQTotalPoint( nPart );GetSSQPrevWinnerNPC🟢 high
Returns the winning side of the previous Seven Signs cycle: 1 = Dusk, 2 = Dawn,
0 — tie/no winner. Scripts compare the result with 2 to find out whether
Dawn won.
Signature
GetSSQPrevWinner( )Parameters
(none — the function is called without arguments)Example
if (GetSSQPrevWinner() == 2) {GetSSQRoundNumberNPC🟢 high
Returns the number of the current Seven Signs period (round) — the counter of competition
cycles. In the example it is used as an item subtype: the "lord of manor's agreement" is
valid within its own round.
Signature
GetSSQRoundNumber( )Parameters
(none — the function is called without arguments)Example
if (IsInCategory(@third_class_group, talker.occupation) == 1 && OwnItemCountEx(talker, 5708, GetSSQRoundNumber()) > 0) {Usage example
if ( IsInCategory( @third_class_group, talker.occupation ) == 1 && OwnItemCountEx( talker, @the_lord_of_manor_s_agreement, GetSSQRoundNumber( ) ) > 0 ) {
ShowPage( talker, szName + "_" + QUEST_ID + "_07.htm" );
}GetTicketBuyCountNPC🟢 high
Returns the number of tickets already bought by the player talker in the current period (a daily limit). A creature method (myself).
Signature
GetTicketBuyCount( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`talker`) whose purchased tickets are countedExample
if ( GetTicketBuyCount( talker ) < ( SSQ_DawnTicketQuantity / SSQ_DawnTicketBundle ) ) {SetTicketBuyCountNPC🟢 high
Sets the player talker's purchased-ticket counter to the value count (usually the current value plus one). No return. A creature method (myself).
Signature
SetTicketBuyCount( CSharedCreatureData c, int nCount )Parameters
c (CSharedCreatureData) — the player (talker) whose ticket counter is set.
nCount (int) — the new value of the purchased-ticket counter (usually current + 1).Example
SetTicketBuyCount( talker, ( GetTicketBuyCount( talker ) + 1 ) );
SetTicketBuyCount(talker, GetTicketBuyCount(talker) + 1);DepositSSQItemExNPC🟢 high
Deposits money into the SSQ manor account when trading seeds and crops. Takes the
recipient (talker), the operation type, and three quantity values, as well as the final
computed coefficient; called on myself. Returns a success flag (1/0).
Signature
DepositSSQItemEx( CSharedCreatureData cCreature, int nPart, int64 nCount1, int64 nCount2, int64 nCount3, int64 nCalcTotal )Parameters
cCreature (CSharedCreatureData) — the recipient creature of the operation (talker).
nPart (int) — the SSQ side: 1 = Dusk, 2 = Dawn. In calls = 2.
nCount1 (int64) — the first quantity (e.g. the number of turned-in seals/seeds; in calls reply or i0).
nCount2 (int64) — the second quantity (in calls 0 if not used).
nCount3 (int64) — the third quantity (in calls 0 if not used).
nCalcTotal (int64) — the final computed value — a weighted sum of the quantities
(e.g. (nCount1 + nCount2) + nCount3 * 10).Example
if ( DepositSSQItemEx( talker, 2, i0, i1, i2, ( ( i0 + i1 ) + ( i2 * 10 ) ) ) ) {Usage example
if ( DepositSSQItemEx( talker, 2, reply, 0, 0, i0 ) ) {
DeleteItem1( talker, @blue_sealstone, reply );
ShowPage( talker, szName + "_" + QUEST_ID + "_25.htm" );
} else {
ShowSystemMessage( talker, 1279 );
}Time Attack
7 functionsGetTimeAttackRecordInfoGLOBAL🟢 high
A method of the global object CGlobalObject. By three numeric keys (event_id, stage_id, rank) and an ordinal index returns a string with information about a time-attack record — the player's name, the completion time, the date.
Signature
GetTimeAttackRecordInfo( int nEventId, int nStageId, int nRank, int nIndex )Parameters
nEventId (int) — the identifier of the time-attack event (`event_id`)
nStageId (int) — the identifier of the time-attack stage (`stage_id`)
nRank (int) — the record's rank (`rank`)
nIndex (int) — the ordinal index of the record in the listExample
s0 = GetTimeAttackRecordInfo( RoomIndex, i1, 1, 0 );GetTimeAttackRewardFlagGLOBAL🟢 high
Checks for a creature whether it has already received the reward for a time-attack run with the given event_id; return: 1 — received, 0 — not.
Signature
GetTimeAttackRewardFlag( CSharedCreatureData cCreature, int nEventId )Parameters
cCreature (CSharedCreatureData) — the creature whose reward receipt is checked
nEventId (int) — the identifier of the time-attack event (`event_id`)Example
if ( GetTimeAttackRewardFlag( talker, 1 ) ) {Usage example
if ( GetTimeAttackRewardFlag( talker, 1 ) ) {
ShowPage( talker, "ssq_main_event_acolyte_q0505_19.htm" );
return;
}IsWinnerOfTimeAttackEventGLOBAL🟢 high
Checks whether a creature is the winner of a time-attack run with the given event_id; return: 1 — yes.
Signature
IsWinnerOfTimeAttackEvent( CSharedCreatureData cCreature, int nEventId )Parameters
cCreature (CSharedCreatureData) — the creature checked for a win in the run
nEventId (int) — the identifier of the time-attack event (`event_id`)Example
if ( IsWinnerOfTimeAttackEvent( talker, 1 ) == 0 ) {Usage example
if ( IsWinnerOfTimeAttackEvent( talker, 1 ) == 0 ) {
ShowPage( talker, "ssq_main_event_acolyte_q0505_17.htm" );
return;
}GetTimeAttackFeeNPC🟢 high
By the numeric event_id returns the entry cost of a time-attack run (in adena). Called on an NPC object.
Signature
GetTimeAttackFee( int nEventId )Parameters
nEventId (int) — the identifier of the run event whose entry cost is returned (in adena).Example
i1 = GetTimeAttackFee( i0 );AddTimeAttackFeeNPC🟢 high
Pays the fee (points) for entry into a time-attack run. Per the L2Server handler (AtomicAddTimeAttackFee::Do →
TimeAttackBoard::AddFee_6BBFB0) the server finds the run's "room" by the event number and ADDS
the passed amount to the accumulated fee value for this room (with a check: an invalid room
or too large a value, above ~100 billion, is rejected with an error to the log). The first argument is
the event/room number, the rest form the accumulated fee amount. Returns the result (1 — success).
Signature
AddTimeAttackFee( int nEventId, int nFee, int nPartyId )Parameters
nEventId (int) — the run event/room number (in calls 1; searched on the time-attack board).
nFee (int) — the fee amount added to the room's accumulated value (in calls 2700).
nPartyId (int) — the id of the participant/party paying the fee (in calls party0.id).Example
AddTimeAttackFee( 1, 2700, party0.id );AddTimeAttackRecordNPC🟢 high
Records a time-attack run record bound to the Seven Signs (SSQ). The roles of the arguments are revealed by
the server function (L2Server: AtomicAddTimeAttackRecord::Do → TimeAttackBoard::AddRecord), its
signature: AddRecord(nRoomNo, SSQPart nPartType, nPartySID, nPoint, nRecordTime, nElapsedTime).
The server checks that the SSQ side is 1 or 2 and that all party members belong to that side
(otherwise system message 1367), adds the points to the accumulated SSQ points of that side (with a
limit check) and writes the record to the DB. Returns 1 on success.
Signature
AddTimeAttackRecord( int nRoomNo, int nSSQPart, int nPartySID, int nPoint, int nRecordTime, int nElapsedTime )Parameters
nRoomNo (int) — the run room/event number (in calls 1).
nSSQPart (int) — the Seven Signs side: 1 = Dusk, 2 = Dawn (in calls 2).
nPartySID (int) — the SID of the participant party (in calls party0.id; all members must be of this SSQ side).
nPoint (int) — the points credited to the SSQ side (in the call OwnItemCount(@q_blood_of_offering); with a limit check).
nRecordTime (int) — the record time (in the call GetTimeOfDay()).
nElapsedTime (int) — the elapsed time (in the call GetMemoState(@blood_offering)).Example
AddTimeAttackRecord( 1, 2, party0.id, OwnItemCount( talker, @q_blood_of_offering ), GetTimeOfDay( ), GetMemoState( talker, @blood_offering ) );GiveTimeAttackRewardNPC🟢 high
Gives a creature the run reward: event_id, item (item_id), and quantity; return: 1 — success. Called on an NPC object.
Signature
GiveTimeAttackReward( CSharedCreatureData c, int nEventId, int nItemId, int nCount )Parameters
c (CSharedCreatureData) — the creature given the reward.
nEventId (int) — the identifier of the run event.
nItemId (int) — the identifier of the reward item.
nCount (int) — the quantity of the reward item.Example
GiveTimeAttackReward( talker, 1, 5575, i1 );Event rooms (Event Room)
3 functionsGetPartyFromEventRoomGLOBAL🟢 high
By the key room_id and the ordinal index party_index returns a party from an event's virtual room.
Signature
GetPartyFromEventRoom( int nRoomId, int nPartyIndex )Parameters
nRoomId (int) — the identifier of the event room (room_id)
nPartyIndex (int) — the ordinal index of the party in the roomExample
party0 = GetPartyFromEventRoom( RoomIndex, SSQPart );Usage example
party0 = GetPartyFromEventRoom( RoomIndex, SSQPart );
if ( IsNull( party0 ) ) { return; }AddPartyToEventRoomGLOBAL🟢 high
Adds a party to an event's virtual room by the keys room_id and party_id with a service parameter; return: 1 — success.
Signature
AddPartyToEventRoom( int nRoomId, int nPartyId, int nArg )Parameters
nRoomId (int) — the identifier of the event room (room_id)
nPartyId (int) — the identifier of the party being added (party_id)
nArg (int) — the service parameter for the addition (in calls — the party object id party0.id)Example
if ( AddPartyToEventRoom( 1, 2, party0.id ) ) {ClearEventRoomGLOBAL🟢 high
Clears an event's virtual room by the key room_id with two service parameters; returns the result.
Signature
ClearEventRoom( int nRoomId, int nArg1, int nArg2 )Parameters
nRoomId (int) — the identifier of the event room (room_id)
nArg1 (int) — the service parameter for clearing
nArg2 (int) — the service parameter for clearingExample
ClearEventRoom( room_index, part_type, 1 );
ClearEventRoom( room_index, part_type, 0 );Gifts & anniversaries (Gifts)
5 functionsIsCreateDateGLOBAL🟢 high
Checks whether the current day falls on the character's creation date. Takes the
recipient (talker); returns 1 (yes) or 0 (no).
Signature
IsCreateDate( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player creature (talker) whose creation date is checkedExample
if ( IsCreateDate( talker ) == 1 ) {CanGetBirthdayGiftGLOBAL🟢 high
Checks whether the player can receive a birthday gift. Takes the recipient
(talker); returns 1 (yes) or 0 (no).
Signature
CanGetBirthdayGift( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player creature (talker) checked for eligibility to receive the giftExample
if ( CanGetBirthdayGift( talker ) == 1 ) {SaveGetBirthdayGiftTimeGLOBAL🟢 high
Saves the time a birthday gift was received (for a subsequent cooldown).
Takes the recipient (talker); returns nothing.
Signature
SaveGetBirthdayGiftTime( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player creature (talker) for whom the gift-issue time is savedExample
SaveGetBirthdayGiftTime( talker );CanGet5YearGiftGLOBAL🟢 high
Checks whether the player can receive the reward for 5 years of play. Takes the recipient
(talker); returns 1 (yes) or 0 (no).
Signature
CanGet5YearGift( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player creature (talker) checked for eligibility to receive the 5-year rewardExample
if (CanGet5YearGift(talker) == 1) {Usage example
if (CanGet5YearGift(talker) == 1) {
GiveItem1( talker, @adena, ( 300 * QuestAdenaRate ) );
SaveGet5YearGiftTimeCount(talker);
ShowPage(talker, "event_master_yogi_5th_success_q01_23.htm");
} else {
ShowPage(talker, "event_master_yogi_5th_failed_q01_24.htm");
}SaveGet5YearGiftTimeCountGLOBAL🟢 high
Saves (increments) the counter of receiving the reward for 5 years of play. Takes the
recipient (talker); returns nothing.
Signature
SaveGet5YearGiftTimeCount( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player creature (talker) whose reward-issue counter is incrementedExample
SaveGet5YearGiftTimeCount(talker);Bingo
6 functionsSelectBingoNumberNPC🟢 high
Selects the cell nCell on the player talker's bingo board; returns the selection result (a success/error code). A creature method (myself).
Signature
SelectBingoNumber( CSharedCreatureData c, int nCell )Parameters
c (CSharedCreatureData) — the player (talker) on whose board the cell is selected.
nCell (int) — the index of the selected bingo board cell.Example
SelectBingoNumber( talker, 1 );IsSelectedBingoNumberNPC🟢 high
Checks whether a number is selected in the cell nCell on the player talker's board; returns 1 if selected, 0 otherwise. A creature method (myself).
Signature
IsSelectedBingoNumber( CSharedCreatureData c, int nCell )Parameters
c (CSharedCreatureData) — the player (talker) on whose board the cell is checked.
nCell (int) — the index of the checked bingo board cell.Example
if ( IsSelectedBingoNumber( talker, i1 ) == 1 ) {Usage example
if ( IsSelectedBingoNumber( talker, i1 ) == 1 ) {
FHTML_SetInt( fhtml0, "Cell" + ( i0 + 1 ), i1 );
} else {
FHTML_SetStr( fhtml0, "Cell" + ( i0 + 1 ), "?" );
}GetNumberFromBingoBoardNPC🟢 high
Extracts the number value from the cell nCell of the player talker's bingo board (by index); returns the number itself. A creature method (myself).
Signature
GetNumberFromBingoBoard( CSharedCreatureData c, int nCell )Parameters
c (CSharedCreatureData) — the player (talker) from whose board the number is read.
nCell (int) — the index of the bingo board cell.Example
i1 = GetNumberFromBingoBoard( talker, i0 );Usage example
i1 = GetNumberFromBingoBoard( talker, i0 );
if ( IsSelectedBingoNumber( talker, i1 ) == 1 ) {
FHTML_SetInt( fhtml0, "Cell" + ( i0 + 1 ), i1 );
} else {
FHTML_SetStr( fhtml0, "Cell" + ( i0 + 1 ), "?" );
}GetBingoSelectCountNPC🟢 high
Returns the number of already-selected numbers on the player talker's board. A creature method (myself).
Signature
GetBingoSelectCount( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`talker`) whose number of selected numbers is countedExample
i3 = GetBingoSelectCount( talker );ClearBingoBoardNPC🟢 high
Resets the player talker's bingo board: zeroes the selection and the selected counter. No return. A creature method (myself).
Signature
ClearBingoBoard( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`talker`) whose bingo board is resetExample
ClearBingoBoard( talker );GetMatchedBingoLineCountNPC🟢 high
Returns the number of matched lines (horizontal, vertical, or diagonal) on the player talker's board. A creature method (myself).
Signature
GetMatchedBingoLineCount( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`talker`) whose matched lines are countedExample
i3 = GetMatchedBingoLineCount( talker );Lotto
11 functionsCanLottoNPC🟢 high
Checks whether the lottery system is enabled on the server; returns 1 (@TRUE) if available, 0 otherwise. Called without an object.
Signature
CanLotto( )Parameters
(none — the function is called without arguments)Example
if (CanLotto() == @TRUE)Lotto_GetStateNPC🟢 high
Returns the current state of the lottery (closed/open, etc.). No arguments. A creature method (myself).
Signature
Lotto_GetState( )Parameters
(none — the function is called without arguments)Example
if ( myself.i_ai0 != Lotto_GetState( ) ) {Usage example
if ( Lotto_GetState( ) != 3 ) {
return;
}Lotto_GetRoundNumberNPC🟢 high
Returns the number of the current lottery round (draw). No arguments. A creature method (myself).
Signature
Lotto_GetRoundNumber( )Parameters
(none — the function is called without arguments)Example
Shout( MakeFString( 1000284, "" + Lotto_GetRoundNumber( ), Lotto_GetChosenNumber( ), "", "", "" ) );Lotto_GetChosenNumberNPC🟢 high
Returns a string of the current lottery round's winning numbers (numbers). No arguments. A creature method (myself).
Signature
Lotto_GetChosenNumber( )Parameters
(none — the function is called without arguments)Example
Shout( MakeFString( 1000284, "" + Lotto_GetRoundNumber( ), Lotto_GetChosenNumber( ), "", "", "" ) );Lotto_GetAccumulatedRewardNPC🟢 high
Returns the total amount of the accumulated jackpot (prize) in the lottery. No arguments. A creature method (myself).
Signature
Lotto_GetAccumulatedReward( )Parameters
(none — the function is called without arguments)Example
FHTML_SetInt( fhtml0, "current_reward", Lotto_GetAccumulatedReward( ) );Lotto_BuyTicketNPC🟢 high
Buys the player talker a lottery ticket with selected numbers and deducts the cost. Per the
L2NPC decompile (CNPC::Lotto_BuyTicket_4A1CF0) the second argument is a bit mask of selected
numbers: the engine counts the set bits and requires exactly 5 (otherwise it logs
"invalid bit flag. hack?"), and the third argument is the cost in adena (item
57=adena is deducted for this amount). The sale is possible only in the LTS_SELLING state. No return.
Signature
Lotto_BuyTicket( CSharedCreatureData c, int nNumbersMask, int nCost )Parameters
c (CSharedCreatureData) — the player (talker) for whom the lottery ticket is bought.
nNumbersMask (int) — the bit mask of selected lottery numbers (exactly 5 bits; in calls reply).
nCost (int) — the ticket cost in adena (deducted; in calls 2000).Example
Lotto_BuyTicket( talker, reply, 2000 );Lotto_GiveRewardNPC🟢 high
Pays out to the player talker the reward for the result reply (the winning number). No return. A creature method (myself).
Signature
Lotto_GiveReward( CSharedCreatureData c, int nResult )Parameters
c (CSharedCreatureData) — the player (talker) to whom the reward is paid out.
nResult (int) — the result/winning number (in calls reply).Example
Lotto_GiveReward( talker, reply );Usage example
if ( ask == -801 ) {
Lotto_GiveReward( talker, reply );
Lotto_ShowCurRewardPage( talker, 0 );
}Lotto_ShowBuyingPageNPC🟢 high
Generates the HTML page of the ticket purchase interface for the player talker (page number page) and fills the fhtml object. No return. A creature method (myself).
Signature
Lotto_ShowBuyingPage( CSharedCreatureData c, int nPage, CFHTML fhtml )Parameters
c (CSharedCreatureData) — the player (talker) who is shown the purchase page.
nPage (int) — the interface page number.
fhtml (CFHTML) — the HTML object to fill.Example
Lotto_ShowBuyingPage( talker, 0, fhtml0 );
Lotto_ShowBuyingPage( talker, talker.param1, fhtml0 );Lotto_ShowCurRewardPageNPC🟢 high
Shows the player talker the list of current (active) rewards/winnings by page page. No return. A creature method (myself).
Signature
Lotto_ShowCurRewardPage( CSharedCreatureData c, int nPage )Parameters
c (CSharedCreatureData) — the player (talker) who is shown the current rewards.
nPage (int) — the list page number.Example
Lotto_ShowCurRewardPage( talker, 0 );
Lotto_ShowCurRewardPage( talker, reply );Lotto_ShowPrevRewardPageNPC🟢 high
Shows the player talker the archive of past rounds and their results by page page. No return. A creature method (myself).
Signature
Lotto_ShowPrevRewardPage( CSharedCreatureData c, int nPage )Parameters
c (CSharedCreatureData) — the player (talker) who is shown the archive of past rounds.
nPage (int) — the archive page number.Example
Lotto_ShowPrevRewardPage( talker, 0 );
Lotto_ShowPrevRewardPage( talker, reply );Lotto_MakeFinalRewardFHTMLNPC🟢 high
Generates the final HTML report of the lottery results and fills the fhtml object. No return. A creature method (myself).
Signature
Lotto_MakeFinalRewardFHTML( CFHTML fhtml )Parameters
fhtml (CFHTML) — the HTML object to fill with the final report.Example
Lotto_MakeFinalRewardFHTML( fhtml0 );Minigame MG (MG)
4 functionsMG_JoinGameNPC🟢 high
Registers the player talker for participation in a minigame and initiates preparation. No return. A creature method (myself).
Signature
MG_JoinGame( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`talker`) registered for participation in the minigameExample
MG_JoinGame( talker );Usage example
if ( ask == -200 ) {
MG_JoinGame( talker );
}
Related event: the server's response arrives as the MG_JOIN_GAME_RETURNED event (see NASC_HANDLERS).MG_SetWinnerNPC🟢 high
Declares the clan clanObj the winner of the minigame (by context — paying out the prize and updating the status). No return. A creature method (myself).
Signature
MG_SetWinner( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the object of the minigame's winner clan (`clanObj`)Example
MG_SetWinner( c0 );
MG_SetWinner( c1 );Usage example
if ( IsNullCreature( c1 ) == 0 && DistFromMe( c1 ) < 1000 ) {
MG_SetWinner( c1 );
BroadcastScriptEvent( 0, 20002, 8000 );
return;
}MG_UnregisterPledgeNPC🟢 high
Removes the player/clan talker's registration from participation in the minigame (bet cancellation). No return. A creature method (myself).
Signature
MG_UnregisterPledge( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player/clan (`talker`) whose minigame registration is removedExample
MG_UnregisterPledge( talker );
Related event: the server's response arrives as the MG_UNREGISTER_PLEDGE_RETURNED event (see NASC_HANDLERS).MG_GetUnreturnedPointNPC🟢 high
Returns the number of points not paid out to the player talker. The semantics of "unreturned points" is reconstructed from a single call. Called without an object.
Signature
MG_GetUnreturnedPoint( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player (`talker`) whose unpaid points are countedExample
MG_GetUnreturnedPoint(talker);
Related event: the server's response arrives as the MG_GET_UNRETURNED_POINT_RETURNED event (see NASC_HANDLERS).Lucky Game
1 functionsShowLuckyGameNPC🟢 high
Opens for the player talker the Lucky Game interface; the argument mode sets the type/mode (for example, 2). No return. Called without an object.
Signature
ShowLuckyGame( CSharedCreatureData cCreature, int nGameType )Parameters
cCreature (CSharedCreatureData) — the player (`talker`) for whom the Lucky Game interface is opened
nGameType (int) — the game type/mode (`mode`)Example
ShowLuckyGame( talker, 2 );
ShowLuckyGame( talker, 1 );FISHING EVENT (Fishing)
4 functionsGetFishingEventRankingNPC🟢 high
Returns the player's place in the fishing event ranking. Takes one argument — the player (talker) of type CSharedCreatureData. Returns an integer.
Signature
GetFishingEventRanking( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player whose place in the fishing event ranking is queriedExample
i0 = GetFishingEventRanking(talker);Usage example
i0 = GetFishingEventRanking(talker);
if (i0 == 0) {
Say("");
} else {
Say(IntToStr(i0) + "");
}ShowHtmlFishingEventRankingNPC🟢 high
Shows the player the fishing event ranking window. Takes one argument — the player (talker) of type CSharedCreatureData. Returns an integer.
Signature
ShowHtmlFishingEventRanking( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player who is shown the fishing event ranking windowExample
ShowHtmlFishingEventRanking(talker);GiveFishingEventPrizeNPC🟢 high
Gives the player a prize for participating in the fishing event — sends the server a command
to grant the reward to the specified player. Takes one argument — the player (talker) of type CSharedCreatureData.
The function is real and working (the event is simply not used in the collected live scripts); the other
fishing functions nearby (ranking, time until reward, ranking window) are genuine too.
Signature
GiveFishingEventPrize( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player who is given the fishing event prizeExample
GiveFishingEventPrize(talker);GetFishingEventRewardRemainTimeNPC🟢 high
Reports how long remains until the next fishing event reward distribution. Takes no arguments. Returns an integer.
Signature
GetFishingEventRewardRemainTime( )Parameters
(none — the function is called without arguments)Example
if (GetFishingEventRewardRemainTime() == @FALSE)Usage example
if (GetFishingEventRewardRemainTime() == 0) {
ShowPage(talker, "no_fish_event_reward001.htm");
} else {
GiveFishingEventPrize(talker);
}PvP matchmaking (PvP Match)
10 functionsUpdatePVPPointNPC🟢 high
Changes the creature's PvP points by the amount delta (may be negative). No return.
Signature
UpdatePVPPoint( CSharedCreatureData c, int nDelta )Parameters
c (CSharedCreatureData) — the creature whose PvP points are changed.
nDelta (int) — the signed amount of the PvP points change (in calls -5000, i4).Example
UpdatePVPPoint(talker, i4);Usage example
if (IsInCategory(@third_class_group, talker.occupation) || IsInCategory(@fourth_class_group, talker.occupation) && talker.level >= 40) {
UpdatePVPPoint(talker, -5000);
IncrementParam(talker, 9, -1);
ShowPage(talker, fnPkDownSuccess);
} else {
ShowPage(talker, fnNoPvpPoint);
}GetPVPPointNPC🟢 high
Returns the creature's current number of PvP points.
Signature
GetPVPPoint( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature whose PvP points are returnedExample
if (GetPVPPoint(talker) < 0)Usage example
if (GetPVPPoint(talker) < 0) {
ShowPage(talker, fnNoPvpPoint);
} else {
ShowMultisell(638, talker);
}RegisterUserPVPMatchNPC🟢 high
Registers a creature for participation in a PvP match. No return.
Signature
RegisterUserPVPMatch( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature registered for the PvP matchExample
RegisterUserPVPMatch( talker );Usage example
if ( talker.level >= 70 && talker.level <= 75 ) {
RegisterUserPVPMatch( talker );
} else {
ShowPage( talker, "cratae_teleport_npc010.htm" );
}
Related event: the server's response arrives as the REGISTER_USER_PVP_MATCH_RESULT event (see NASC_HANDLERS).UnregisterUserPVPMatchNPC🟢 high
Cancels a creature's registration in a PvP match. No return.
Signature
UnregisterUserPVPMatch( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature whose PvP match registration is cancelledExample
UnregisterUserPVPMatch( talker );
UnregisterUserPVPMatch( creature );
UnregisterUserPVPMatch( c0 );Usage example
if ( InMyTerritory( c0 ) == 0 ) {
UnregisterUserPVPMatch( c0 );
}
Related event: the server's response arrives as the UNREGISTER_USER_PVP_MATCH_RESULT event (see NASC_HANDLERS).IsUserPVPMatchingNPC🟢 high
A diagnostic function: checks whether a creature is registered in a PvP match.
Signature
IsUserPVPMatching( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature checked for registration in a PvP matchExample
IsUserPVPMatching( creature );Usage example
if ( creature.is_pc == @TRUE ) {
IsUserPVPMatching( creature );
}
Related event: the server's response arrives as the IS_USER_PVPMATCHING_RESULT event (see NASC_HANDLERS).CheckRegisterUserPVPMatchNPC🟢 high
A diagnostic function: validates the preconditions for a creature's registration in a PvP match.
Signature
CheckRegisterUserPVPMatch( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature for which the PvP match registration preconditions are checkedExample
CheckRegisterUserPVPMatch( talker );
Related event: the server's response arrives as the CHECK_REGISTER_USER_RESULT event (see NASC_HANDLERS).AddKillPointUserPVPMatchNPC🟢 high
Adds kill points to a creature in a PvP match (kill_points). No return.
Signature
AddKillPointUserPVPMatch( CSharedCreatureData c, int nKillPoints )Parameters
c (CSharedCreatureData) — the creature credited with kill points.
nKillPoints (int) — the number of kill points added.Example
AddKillPointUserPVPMatch( c0, i0 );
AddKillPointUserPVPMatch(c0, my_point);Usage example
if ( IsNullCreature( c0 ) == 0 ) {
AddKillPointUserPVPMatch( c0, i0 );
AddHateInfo( c0, i0, 0, 1, 1 );
}GetRankUserPVPMatchNPC🟢 high
A diagnostic function: returns a creature's current rating/rank in the PvP ranking.
Signature
GetRankUserPVPMatch( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the creature whose PvP-ranking rank is returnedExample
GetRankUserPVPMatch( c0 );Usage example
if ( IsNullCreature( c0 ) == 0 ) {
GetRankUserPVPMatch( c0 );
}
Related event: the server's response arrives as the GET_RANK_USER_PVP_MATCH_RESULT event (see NASC_HANDLERS).UnregisterPVPMatchNPC🟢 high
Cancels a party's registration from a team PvP match; takes a party and a creature. No return.
Signature
UnregisterPVPMatch( CSharedPartyData party, CSharedCreatureData c )Parameters
party (CSharedPartyData) — the party being removed from match registration.
c (CSharedCreatureData) — the creature (the party's initiator/representative) from whom the cancellation comes.Example
UnregisterPVPMatch(party0, c0);
UnregisterPVPMatch(party1, c2);
UnregisterPVPMatch(party0, talker);Usage example
if (IsNullCreature(c1) == 0) {
UnregisterPVPMatch(party0, c0);
}
Related event: the server's response arrives as the UNREGISTER_PVP_MATCH_RESULT event (see NASC_HANDLERS).GetStatusForOlympiadFieldNPC🟢 high
By the numeric field_id returns the Olympiad field status: 0 — free, 1 — occupied. Called on an NPC object.
Signature
GetStatusForOlympiadField( int nFieldId )Parameters
nFieldId (int) — the number of the Olympiad field whose status is requested (return: 0 — free, 1 — occupied).Example
if ( GetStatusForOlympiadField( i0 ) == 0 ) {Usage example
if (GetStatusForOlympiadField(i0) == 0) {
FHTML_SetStr(fhtml0, "Status" + i0, "&$906;");
}Team events (Team Event)
10 functionsTeamGetMembersCountNPC🟢 high
By the keys event_id and team_id returns the number of members in a team.
Signature
TeamGetMembersCount( int nEventId, int nTeamId )Parameters
nEventId (int) — the identifier of the team event
nTeamId (int) — the identifier of the team within the eventExample
i8 = TeamGetMembersCount( my_Event, i0 );
i9 = TeamGetMembersCount( my_Event, 1 );
i9 = TeamGetMembersCount( my_Event, 2 );
i3 = TeamGetMembersCount( my_Event, talker.m_nPvP_Event_TeamId );Usage example
i3 = TeamGetMembersCount( my_Event, talker.m_nPvP_Event_TeamId );
if ( i1 == 0 ) { i2 = myself.sm.subjob0_class + myself.sm.subjob1_class; i3 = TeamGetMembersCount( my_Event, 1 ) + TeamGetMembersCount( my_Event, 2 ); }TeamEventGetStatusNPC🟢 high
By event_id returns the team event status: 0 — inactive, 1 — active.
Signature
TeamEventGetStatus( int nEventId )Parameters
nEventId (int) — the identifier of the team event whose status is requestedExample
if ( TeamEventGetStatus( my_Event ) == @TEAMEVENT_STATUS_BATTLE ) {Usage example
if ( TeamEventGetStatus( my_Event ) == @TEAMEVENT_STATUS_NOMINATION ) {
SendScriptEventEx( myself.sm, seDirectorShowPage, pageNomination, talker.id ); // show the results output page
}TeamEventSetStatusNPC🟢 high
Sets the status of a team event by event_id and the value status. No return.
Signature
TeamEventSetStatus( int nEventId, int nStatus )Parameters
nEventId (int) — the identifier of the team event
nStatus (int) — the new event status (0 — inactive, 1 — active)Example
TeamEventSetStatus( my_Event, @TEAMEVENT_STATUS_REGISTRATION);Usage example
if ( timer_id == timer_teleport ) { // teleport the teams to town
TeamEventSetStatus( my_Event, @TEAMEVENT_STATUS_NOMINATION );
TeamInstantTeleport(my_Event, 1, Return_X, Return_Y, Return_Z );
TeamInstantTeleport(my_Event, 2, Return_X, Return_Y, Return_Z );
InstantTeleportInMyTerritory( Return_X, Return_Y, Return_Z, 50 );
}TeamShowSystemMessage2NPC🟢 high
Shows a system message to all members of a team: event_id, team_id, msg_id, the number of parameters, and the parameters themselves (unused ones — _blank).
Signature
TeamShowSystemMessage2( int nEventId, int nTeamId, int nSysMsgNo, int nParamCount, string pwsParam1, string pwsParam2, string pwsParam3, string pwsParam4, string pwsParam5, string pwsParam6, string pwsParam7 )Parameters
nEventId (int) — the identifier of the team event
nTeamId (int) — the identifier of the team the message is sent to
nSysMsgNo (int) — the system message number
nParamCount (int) — the number of filled message parameters
pwsParam1 (string) — the 1st substitution parameter into the system message
pwsParam2 (string) — the 2nd substitution parameter into the system message
pwsParam3 (string) — the 3rd substitution parameter into the system message
pwsParam4 (string) — the 4th substitution parameter into the system message
pwsParam5 (string) — the 5th substitution parameter into the system message
pwsParam6 (string) — the 6th substitution parameter into the system message
pwsParam7 (string) — the 7th substitution parameter into the system messageExample
TeamShowSystemMessage2( my_Event, 1, 1983, 1, s0, _blank, _blank, _blank, _blank, _blank, _blank );Usage example
if ( timer_id == 33328 ) { // message: Teleport in 1
TeamShowSystemMessage2( my_Event, my_Team, sysCenterRed, 1, MakeFString( 3223119, "1", _blank, _blank, _blank, _blank ), _blank, _blank, _blank, _blank, _blank, _blank );
AddTimerEx( 33323, 1000 );
}TeamGetMemberByIndexNPC🟢 high
By the keys event_id, team_id, and member_index returns a creature — a team member.
Signature
TeamGetMemberByIndex( int nEventId, int nTeamId, int nMemberIndex )Parameters
nEventId (int) — the identifier of the team event
nTeamId (int) — the identifier of the team within the event
nMemberIndex (int) — the ordinal index of the team memberExample
c0 = TeamGetMemberByIndex( my_Event, i0, 0 );
c0 = TeamGetMemberByIndex( my_Event, i0, i1 );
c0 = TeamGetMemberByIndex( my_Event, 1, i8 );
c0 = TeamGetMemberByIndex( my_Event, 2, i8 );Usage example
c0 = TeamGetMemberByIndex( my_Event, i0, i1 );
if ( IsNullCreature( c0 ) == 0 ) {
GiveItem1( c0, defaultCostID, defaultCostAmount ); // return the entry fee
}TeamAddMemberNPC🟢 high
Adds a creature to a team by the keys event_id and team_id; returns the result.
Signature
TeamAddMember( int nEventId, int nTeamId, CSharedCreatureData target )Parameters
nEventId (int) — the identifier of the team event
nTeamId (int) — the identifier of the team the member is added to
target (CSharedCreatureData) — the creature (player) added to the teamExample
TeamAddMember( my_Event, 1, c0 );
TeamAddMember( my_Event, 2, c0 );
TeamAddMember( my_Event, 3, talker );
TeamAddMember( my_Event, 4, talker );Usage example
if ( TeamGetMembersCount( my_Event, 4) < 100 ) { // if team 4 is not yet full — add to it
TeamAddMember( my_Event, 4, talker );
}TeamRemoveMemberNPC🟢 high
Removes a creature from a team; returns the result.
Signature
TeamRemoveMember( CSharedCreatureData target )Parameters
target (CSharedCreatureData) — the creature (player) removed from the teamExample
TeamRemoveMember( c0 );
TeamRemoveMember( target );Usage example
if ( IsNullCreature( c0 ) == 0 ) {
TeamRemoveMember( c0 );
if ( myself.i_quest4 > 0 ) {
GiveItem1( c0, myself.i_quest3, myself.i_quest4 );
}
}TeamSetRestartPointNPC🟢 high
Sets the respawn point for a team by the keys event_id, team_id and the coordinates x, y, z; returns the result.
Signature
TeamSetRestartPoint( int nEventId, int nTeamId, int nX, int nY, int nZ )Parameters
nEventId (int) — the identifier of the team event
nTeamId (int) — the identifier of the team whose respawn point is set
nX (int) — the X coordinate of the respawn point
nY (int) — the Y coordinate of the respawn point
nZ (int) — the Z coordinate of the respawn pointExample
TeamSetRestartPoint(my_Event, 1, 147574, 46717, -3400);
TeamSetRestartPoint(my_Event, 2, 151496, 46717, -3400);TeamGetInactiveCharactersNPC🟢 high
By the keys event_id, team_id and the idle threshold in seconds (timeout_sec) returns the inactive team members.
Signature
TeamGetInactiveCharacters( int nEventId, int nTeamId, int nInactiveTimeSec )Parameters
nEventId (int) — the identifier of the team event
nTeamId (int) — the identifier of the team
nInactiveTimeSec (int) — the idle threshold in seconds after which a member is considered inactiveExample
TeamGetInactiveCharacters( my_Event, 1, checkInnactiveCharPeriod * 60 );
TeamGetInactiveCharacters( my_Event, 2, checkInnactiveCharPeriod * 60 );Usage example
if ( TeamEventGetStatus( my_Event ) == @TEAMEVENT_STATUS_BATTLE ) {
TeamGetInactiveCharacters( my_Event, 1, checkInnactiveCharPeriod * 60 );
TeamGetInactiveCharacters( my_Event, 2, checkInnactiveCharPeriod * 60 );
AddTimerEx( 33319, checkInnactiveCharPeriod * 60000 );
}TeamEventAddMembersWithBalanceNPC🟢 high
Adds members to an event with automatic balancing: event_id, the member list, the number of teams (teams_count), and the category range (category_from, category_to); returns the result.
Signature
TeamEventAddMembersWithBalance( int nEventId, CIntList pIntList, int nTeamsNumber, int nBalanceCategoryFrom, int nBalanceCategoryTo )Parameters
nEventId (int) — the identifier of the team event
pIntList (CIntList) — the list of identifiers of the added members
nTeamsNumber (int) — the number of teams the participants are distributed across
nBalanceCategoryFrom (int) — the lower bound of the balancing category
nBalanceCategoryTo (int) — the upper bound of the balancing categoryExample
i0 = TeamEventAddMembersWithBalance( my_Event, myself.db_int_list, 2, tvt_group_start, tvt_group_end );Cleft event (Cleft)
5 functionsGetCleftStateNPC🟢 high
Getter (CNPC), no arguments. Returns int — the current state of the Cleft zone (the rift).
Signature
GetCleftState( )Parameters
(none — the function is called without arguments)Example
if ( GetCleftState( ) != 2 ) {Usage example
if ( GetCleftState( ) != 2 ) {
return;
}CleftManagerEnterNPC🟢 high
Initializes the cleft (Cleft) manager; called on zone creation.
Takes no arguments and returns nothing.
Signature
CleftManagerEnter( )Parameters
(none — the function is called without arguments)Example
CleftManagerEnter();CleftUserEnterNPC🟢 high
Registers a player in the cleft system for tracking participants. Takes the
recipient (talker); returns nothing.
Signature
CleftUserEnter( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player creature (talker) registered in the cleft systemExample
CleftUserEnter(talker);Usage example
if (IsCleftUser(talker) == 0) {
CleftUserEnter(talker);
} else {
ShowPage(talker, fnNoEnter);
}IsCleftUserNPC🟢 high
Checks whether a player is a participant in the cleft. Takes the recipient
(talker); returns 0 (no) or 1 (yes).
Signature
IsCleftUser( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player creature (talker) checked for participation in the cleftExample
if (IsCleftUser(talker) == 0) {Usage example
if (IsCleftUser(talker) == 0) {
CleftUserEnter(talker);
} else {
ShowPage(talker, fnNoEnter);
}CleftCenterDestroyedNPC🟢 high
Handles the destruction of the cleft center and triggers the completion events.
Takes the zone type, a creature, and the destruction point; returns nothing.
Signature
CleftCenterDestroyed( int nZoneType, CSharedCreatureData c, int nDestroyPoint )Parameters
nZoneType (int) — the cleft zone type.
c (CSharedCreatureData) — the creature associated with the center destruction.
nDestroyPoint (int) — the destruction point (position value) of the center.Example
CleftCenterDestroyed( ZoneType, myself.c_ai0, DestroyPoint );Block Checker (Block Upset)
6 functionsBlockUpsetNPC🟢 high
Registers a participant of the BlockUpset minigame on the ground. Per the L2Server handler
(NpcSocket::NpcBlockUpset_756428) packet opcode 187 is a sub-command dispatcher by the first field;
the BlockUpset call corresponds to sub-command 1 → CBlockUpsetManager::AddBlockUpsetPoint (adds
a point/participant to the ground GroundID). The handler uses the participant creature and the ground id;
the second argument (nInitParam) is 0 in all calls and is not consumed by the registration path —
a reserved field. Returns nothing.
Signature
BlockUpset( int nGroundId, int nInitParam, CSharedCreatureData c, int nStartPoint )Parameters
nGroundId (int) — the game ground identifier (GroundID).
nInitParam (int) — a reserved service field (always 0 in calls; not used by the server during registration).
c (CSharedCreatureData) — the participant creature (speller) added to the ground.
nStartPoint (int) — the participant's start point (BlockUpsetPoint).Example
BlockUpset( GroundID, 0, speller, BlockUpsetPoint );
BlockUpset( GroundID, 0, GetCreatureFromIndex( script_event_arg2 ), BlockUpsetPoint );Usage example
if ( script_event_arg1 == 9999 ) {
BlockUpset( GroundID, 0, GetCreatureFromIndex( script_event_arg2 ), BlockUpsetPoint );
SetVisible( 0 );
AddTimerEx( 1000, 3000 );
}BlockUpsetChangeAmountNPC🟢 high
Changes the number of blocks in the current game (14, 16, or 20). Takes the ground identifier
(GroundID) and the count; returns nothing.
Signature
BlockUpsetChangeAmount( int nGroundId, int nBlockCount )Parameters
nGroundId (int) — the game ground identifier (GroundID).
nBlockCount (int) — the number of blocks (14, 16, or 20).Example
BlockUpsetChangeAmount( GroundID, 16 );
BlockUpsetChangeAmount( GroundID, 20 );
BlockUpsetChangeAmount( GroundID, 14 );Usage example
if ( timer_id == 2000 ) {
BlockUpsetChangeAmount( GroundID, 14 );
}BlockUpsetChangeColorNPC🟢 high
Switches the block color (0 or 1) to change the difficulty level. Takes the
ground identifier (GroundID) and the color identifier (ColorID); returns
nothing.
Signature
BlockUpsetChangeColor( int nGroundId, int nColorId )Parameters
nGroundId (int) — the game ground identifier (GroundID).
nColorId (int) — the block color identifier (ColorID, 0 or 1).Example
BlockUpsetChangeColor( GroundID, ColorID );BlockUpsetRegisterMeNPC🟢 high
Registers the current NPC as part of the game instance. Takes the ground identifier
(GroundID); returns nothing.
Signature
BlockUpsetRegisterMe( int nGroundId )Parameters
nGroundId (int) — the game ground identifier (GroundID) to which the NPC is bound.Example
BlockUpsetRegisterMe( GroundID );BlockUpsetUserEnterNPC🟢 high
Brings a player into the BlockUpset instance and prepares its state. Takes the
ground identifier (GroundID) and the recipient (talker); returns nothing.
Signature
BlockUpsetUserEnter( int nGroundId, CSharedCreatureData c )Parameters
nGroundId (int) — the game ground identifier (GroundID).
c (CSharedCreatureData) — the player creature (talker) brought into the instance.Example
BlockUpsetUserEnter( GroundID, talker );BlockUpsetManagerEnterNPC🟢 high
Initializes the game manager; called once on instance creation.
Takes the ground identifier (GroundID); returns nothing.
Signature
BlockUpsetManagerEnter( int nGroundId )Parameters
nGroundId (int) — the game ground identifier (GroundID) for which the manager is created.Example
BlockUpsetManagerEnter( GroundID );Misc events & system (Misc)
11 functionsIsUserLockedGLOBAL🟢 high
Checks whether the player is in a locked status. Takes the recipient
(talker); returns 1 (locked) or 0 (no).
Signature
IsUserLocked( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the player creature checked for lock statusExample
if ( IsUserLocked( talker ) ) {Usage example
if ( IsUserLocked( talker ) ) {
ShowPage( talker, "locked_user.htm" );
return;
}GetRank_RimKamarokaGLOBAL🟢 high
Returns a string with the player's data in the Rim/Kamaroka boss ranking. Takes the
level and the request type (2 — rank, 4 — XP); returns a string.
Signature
GetRank_RimKamaroka( int nRimType, int nLevel )Parameters
nRimType (int) — the type of ranking-data request (2 — rank, 4 — XP)
nLevel (int) — the level for which the ranking data is requestedExample
if ( IsSameString( GetRank_RimKamaroka( i6, 2 ), _blank ) == 1 ) {Usage example
if ( i6 >= 7 && i6 <= 14 && IsSameString( GetRank_RimKamaroka( ( i6 - 5 ), 2 ), _blank ) != 1 ) {
if ( babble_mode == 1 ) { Shout( "Rank propagation " + IntToStr( i6 - 5 ) ); }
s0 = MakeFString( 1800200, _blank, _blank, _blank, _blank, _blank );
Say( MakeFString( 1800202, GetRank_RimKamaroka( ( i6 - 5 ), 2 ), s0, _blank, _blank, _blank ) );
} else {
if ( babble_mode == 1 ) { Shout( "Rank propagation failed" ); }
}Party_GetSubLeaderGLOBAL🟢 high
Returns the sub-leader of the player's party. Takes the recipient (talker);
returns an object/creature (in the example assigned to a creature-type variable).
Signature
Party_GetSubLeader( CSharedCreatureData cCreature )Parameters
cCreature (CSharedCreatureData) — the player creature (talker) whose party is queried for the sub-leaderExample
c1 = Party_GetSubLeader(talker);BroadCastUIEventNpcStrGLOBAL🟢 high
Broadcasts a UI event (for example, an airship one) to all players in a zone. Takes an NPC,
the event identifier, and a set of numeric and string parameters (coordinates,
message); returns nothing.
Signature
BroadCastUIEventNpcStr( CSharedCreatureData cCreature, int nRange, int nShowTimer, int nUnk1, int nUnk2, string pwsTimerType, string pwsStartTimeMin, string pwsStartTimeSec, int nNpcStringId, string pwsEndTimeMin, string pwsEndTimeSec )Parameters
cCreature (CSharedCreatureData) — the source NPC of the broadcast UI event
nRange (int) — the broadcast radius of the event around the NPC
nShowTimer (int) — the flag for displaying the timer
nUnk1 (int) — a service numeric parameter of the event
nUnk2 (int) — a service numeric parameter of the event
pwsTimerType (string) — the timer type of the event
pwsStartTimeMin (string) — the minutes of the timer's start time
pwsStartTimeSec (string) — the seconds of the timer's start time
nNpcStringId (int) — the identifier of the NPC string for the message
pwsEndTimeMin (string) — the minutes of the timer's end time
pwsEndTimeSec (string) — the seconds of the timer's end timeExample
BroadCastUIEventNpcStr( myself.sm, 2000, 0, 0, 0, "0", IntToStr( myself.i_ai2 ), "00", SUMMON_AIRSHIP_MESSAGE_ID + 3 , "0", "0" );
================================================================================
================================================================================
PART II. NPC FUNCTIONS
================================================================================
================================================================================
Methods of the character (NPC) itself. Called in NPC scripts; the notation is short,
without `myself.` (the receiver is the character itself).CheckRegisterParty2NPC🟢 high
A diagnostic function: validates whether two parties can register for a team match.
Signature
CheckRegisterParty2( CSharedPartyData party1, CSharedPartyData party2 )Parameters
party1 (CSharedPartyData) — the first party registered for the team match.
party2 (CSharedPartyData) — the second party checked for the possibility of joint registration.Example
CheckRegisterParty2(party0, party1);Usage example
if (myself.i_quest0 == 1 && myself.i_quest3 == 1) {
CheckRegisterParty2(party0, party1);
}IsEventDropTimeNPC🟢 high
Checks whether the event drop time is currently in effect. Takes no arguments;
returns 1 (yes) or 0 (no).
Signature
IsEventDropTime( )Parameters
(none — the function is called without arguments)Example
if ( IsEventDropTime( ) == 1 ) {Usage example
if ( IsEventDropTime( ) == 1 ) {
ShowPage( talker, fnHi );
} else {
ShowPage( talker, fnHi2 );
}SetPrivateIDNPC🟢 high
Sets the private identifier for an NPC/object. Takes the ID value (often
the product of part_type by room_index); called on myself, returns
nothing.
Signature
SetPrivateID( int nId )Parameters
nId (int) — the private identifier assigned to the NPC/object (often part_type * room_index).Example
SetPrivateID( ( part_type * room_index ) );GetPlayingUserCountNPC🟢 high
Returns the number of active players on the server. Takes no arguments;
the returned value is not used explicitly in the decoded scripts.
Signature
GetPlayingUserCount( )Parameters
(none — the function is called without arguments)Example
GetPlayingUserCount( );IsAutoMacroUseNPC🟢 high
Checks whether a player uses macros. Takes the target (target); returns
1 (yes) or 0 (no), in the example compared with @TRUE.
Signature
IsAutoMacroUse( CSharedCreatureData c )Parameters
c (CSharedCreatureData) — the target creature (target) checked for macro usageExample
if (HaveMemo(target, @c_development_quest70) == @TRUE && GetMemoState(target, @c_development_quest70) == 2 && IsAutoMacroUse( target ) == @TRUE)Usage example
if (HaveMemo(target, @c_development_quest70) == @TRUE && GetMemoState(target, @c_development_quest70) == 2 && IsAutoMacroUse( target ) == @TRUE)
{
i0 = @c_development_quest70;
i1 = @c_development_item7;
i2 = 100;
i3 = 15;
}RegisterPledgeUpEventListenerNPC🟢 high
Registers a listener for clan level-up events. Takes no arguments and
returns nothing.
Signature
RegisterPledgeUpEventListener( )Parameters
(none — the function is called without arguments)Example
RegisterPledgeUpEventListener();XMasEventManagerEnterNPC🟢 high
Initializes the Christmas event (Xmas). Takes no arguments and returns
nothing.
Signature
XMasEventManagerEnter( )Parameters
(none — the function is called without arguments)Example
XMasEventManagerEnter();Usage example
if (is_main_manager) {
XMasEventManagerEnter();
}
================================================================================
================================================================================
PART III. MAKER (SPAWNER) FUNCTIONS
================================================================================
================================================================================
Methods of the spawner/maker (NpcMaker) — spawning and respawning NPCs, registering
territory events. Called in NpcMaker scripts.LOGGING (Log)
8 functionsAddLogGLOBAL🟢 high
Adds an entry to the player action log: the first argument is nLogType — the
entry type code, the second is the player c, the third is the related identifier nParam.
The type defines the meaning: 1 — quest acceptance, 2 — progress update, 3 — completion (the
three most common), 6 — item obtained; other codes (4, 7–11 and named constants of the@LOG_* form from [manual_pch]) cover other categories. Important subtlety: the namespace
of the third argument depends on the type — for quest types 1/2/3 it is a quest id [quest_pch],
while for 6 it is the id of the item [item_pch] that was just given out; the function returns
nothing meaningful.
Signature
AddLog( int nLogType, CSharedCreatureData cCreature, int nParam )Parameters
nLogType (int) — log entry category code. Named constants [manual_pch] @LOG_*:
1 GET_NOBLESS_GATE_PASS · 2 ERROR · 3 DEBUG · 4 OF_TIMEATTACK ·
7 ENTER_CREVICE_OF_THE_DIMENSION · 8 LEAVE_CREVICE · 9 ENTER_ROYAL_RUSH ·
10 CASTLE_WIZARD_TELEPORT · 111 PCCAFE_POINT_BUFF · 324 USE_CHANCE_CARD.
NB: the observed usage of the small values with quests does NOT match these names
(1/2/3 come massively with quest_id — by context the quest stages accept/progress/complete,
6 — with an item id), i.e. the first argument is treated as a log category code, and some
values (5, 6, 11) have no named constant at all.
cCreature (CSharedCreatureData) — the player.
nParam (int) — related id; the namespace depends on the category: for quest values — [quest_pch],
for "item obtained" (6) — [item_pch].Example
AddLog( 2, talker, @deliver_goods );AddLogExGLOBAL🟢 high
Extended version of AddLog with an additional numeric field nParam2. Takes nLogType
(event type code), the player c, and two related values nParam and nParam2; the namespace
of the fields depends on the event type. Belongs to the global object.
Signature
AddLogEx( int nLogType, CSharedCreatureData cCreature, int nParam, int nParam2 )Parameters
nLogType (int) — log entry category code (same space as AddLog: @LOG_* constants
from [manual_pch], e.g. @LOG_USE_CHANCE_CARD=324; script-defined ones like Log_pc_LevDiff also occur).
cCreature (CSharedCreatureData) — the player associated with the entry
nParam (int) — first related value of the entry (namespace depends on the category)
nParam2 (int) — second related value of the entryExample
AddLogEx(@LOG_USE_CHANCE_CARD, talker, RoomIndex, i0);Usage example
if ( log_mode == 1 ) {
AddLogEx( Log_pc_LevDiff, attacker, i0, 0 );
}AddScriptLogGLOBAL🟢 high
Writes an arbitrary string entry to the script log: a debug and diagnostic
message with a numeric tag nLogId and text sText. Serves for tracing script
logic and is not visible to the player. Belongs to the global object.
Signature
AddScriptLog( int nLogId, string sText )Parameters
nLogId (int) — numeric tag of the entry. @LOG_ERROR (2) and raw 2/3 occur; an arbitrary
debug-log category tag (does not affect gameplay).
sText (string) — log text.Example
AddScriptLog( 3, "... all ok" );Usage example
if (i2 > 5) {
AddScriptLog(3, "[" + myself.sm.name + "] try return 5000 CRP to [ " + talker.name + "]");
}AddLogExWithoutCreatureGLOBAL🟢 high
An extended version of logging that writes a record not bound to a creature — for
system and global events where there is no specific player. Takes nLogType (the event-type
code) and two related values nParam and nParam2. Belongs to the global
object.
Example
AddLogExWithoutCreature(Log_NoKilling, i0, 0);
AddLogExWithoutCreature(Log_ChainSpawnSuccess, i0, 0);
AddLogExWithoutCreature(Log_MobClearing, i0, 0);Usage example
if (log_mode == 1) {
AddLogExWithoutCreature(Log_ChainSpawnSuccess, i0, 0);
}AddLogByNpcNPC🟢 high
Logging on behalf of an NPC: the record is attributed to a specific NPC, not to the global
system. The server merely writes a tag and two numbers to the log (does not affect gameplay),
so the tag is an open set of analytics codes set by script convention, not
a fixed enum. Belongs to the NPC.
Signature
AddLogByNpc( int nLogTag, CSharedCreatureData c, int nParam1, int nParam2 )Parameters
nLogTag (int) — the log record tag/type (an open analytics set; in calls
122, 326, 413, 414, 416, 899, 8057, etc. are found — the meaning is set by the script analytics).
c (CSharedCreatureData) — the player associated with the record.
nParam1 (int) — the first number of the record (an analytics value per the tag's meaning).
nParam2 (int) — the second number of the record (an analytics value per the tag's meaning).Example
AddLogByNpc(122, talker, 1, 0);AddLogByNpc2NPC🟢 high
A detailed version of logging on behalf of an NPC for detailed telemetry of its actions
(rewards, sales, events). Takes nLogId (the record type/tag), the associated player c,
two string fields s1 and s2, and up to six large numeric fields nP1..nP6 (int64).
Belongs to the NPC.
Signature
AddLogByNpc2( int nLogId, CSharedCreatureData pCreatureShared, string sStr1, string sStr2, int64 nParam1, int64 nParam2, int64 nParam3, int64 nParam4, int64 nParam5, int64 nParam6 )Parameters
nLogId (int) — the log record type/tag
pCreatureShared (CSharedCreatureData) — the player associated with the record
sStr1 (string) — the first string field of the record
sStr2 (string) — the second string field of the record
nParam1 (int64) — the first large numeric field of the record
nParam2 (int64) — the second large numeric field of the record
nParam3 (int64) — the third large numeric field of the record
nParam4 (int64) — the fourth large numeric field of the record
nParam5 (int64) — the fifth large numeric field of the record
nParam6 (int64) — the sixth large numeric field of the recordExample
AddLogByNpc2(127, target, "ADDLOG", "RANGE_OVER", 0, 0, 0, 0, 0, 0);Usage example
if ( babble_mode > 0 ) {
AddLogByNpc2( 127, myself.sm, "antaras_test", "MY_DYING: dead and combat terminated", 0, 0, 0, 0, 0, 1 );
}GetNPCLogByIDNPC🟢 high
Reads the current value of the built-in "killed/collected X" counter for a quest — a table
on the character separate from the memo-state (up to 40 slots). The record key is the triple of nQuestId
(the quest [quest_pch]), nQuestState (the quest stage), and nNpcId (the class of the NPC whose kills
are counted); the first argument passes the player pTalker. Returns the accumulated
counter value. Belongs to the NPC.
Signature
GetNPCLogByID( CSharedCreatureData pTalker, int nQuestId, int nQuestState, int nNpcId )Parameters
pTalker (CSharedCreatureData) — 2.
nQuestId (int) — 2.
the values are from the [quest_pch] dictionary
nQuestState (int) — the quest stage — part of the counter key
nNpcId (int) — 4 (Increase).Example
if (GetNPCLogByID(last_attacker, @one_stroke_one_kill, 0, i3) < 10)Usage example
if (_from_choice == 0 || (HaveMemo(talker, @one_stroke_one_kill) == @TRUE && GetMemoState(talker, @one_stroke_one_kill) == 1 && GetNPCLogByID(talker, @one_stroke_one_kill, 0, 1018879) < 1 && GetNPCLogByID(talker, @one_stroke_one_kill, 0, 1018886) < 1 && GetNPCLogByID(talker, @one_stroke_one_kill, 0, 1018893) < 1 && GetNPCLogByID(talker, @one_stroke_one_kill, 0, 1018900) < 1)) {
SetCurrentQuestID(@one_stroke_one_kill);
ShowPage(talker, "keleia_q0458_13.htm");
}IncreaseNPCLogByIDNPC🟢 high
Increases the built-in "killed/collected X" counter by 1, but no higher than the ceiling nMaxValue
(convenient for "kill N mobs" tasks: on reaching the ceiling, the counter no longer grows). The record
key is the triple of nQuestId (the quest [quest_pch]), nQuestState (the quest stage), and nNpcId
(the NPC class); the first argument passes the player pTarget, the fifth — nMaxValue (the ceiling).
Belongs to the NPC.
Signature
IncreaseNPCLogByID( CSharedCreatureData pTarget, int nQuestId, int nQuestState, int nNpcId, int nMaxValue )Parameters
pTarget (CSharedCreatureData) — the player on whose character the counter is stored
nQuestId (int) — the quest — part of the counter key; the quest choice from the [quest_pch] dictionary
the values are from the [quest_pch] dictionary
nQuestState (int) — the quest stage — part of the counter key
nNpcId (int) — the class of the NPC whose kills/collection are counted — part of the counter key
nMaxValue (int) — the counter ceiling above which it does not growExample
IncreaseNPCLogByID( target, 453, 0, @kiriona, 20 );