Looking up players from scripts

From fkdr 0.44.58 a script can look up any player on Hypixel, Urchin and Aurora: stats, guild, online status, recent games, tags, ping and winstreak. fkdr makes the request with the keys you set in Configs → api keys and hands the answer to your script.

fkdr.hypixel.player('Notch', function (r) {
    if (!r.ok) { chat.print('§c' + r.message); return; }
    chat.print(r.name + ': ' + r.stats.star + '✫, ' + r.stats.fkdr + ' FKDR');
});

Three services are available:

service	what you get	needs a key
fkdr.hypixel	stats, guild, online status, recent games, and a set of other read-only Hypixel answers	your Hypixel key (some answers work without one)
fkdr.urchin	Urchin tags and the reason given	your Urchin key
fkdr.aurora	stats, ping and winstreak estimates	no

Set your keys in Configs → api keys (see API keys). A script never sees them, and cannot read them in any way.

Every function name, reply field and code is on the lookup reference. Short, complete scripts are on lookup examples.

How a lookup works

1. Your script asks, with a player's name or UUID and a function to call with the answer.
2. fkdr sends the request, or answers straight away from what it already knows.
3. Your function runs on the client thread with a reply, so it can print, draw or change settings directly.

Every lookup answers exactly once, whether it worked or not. r.ok says which; when it is false, r.code says why (no_key, not_found, busy …) and r.message is a sentence you can show the player.

A lookup never throws, and there is no way to wait for one. If your script is switched off or reloaded before the answer arrives, the answer is dropped.

Limits and caching

You do not need to manage rate limits yourself.

• Requests wait their turn instead of failing. Each script has its own pace per service. Ask for more than that and the extra lookups are queued and sent a little apart. A reply says how long it waited (r.waited, in milliseconds). Only a lookup that would have to wait a long time is refused, with too_many and r.retryIn.
• fkdr comes first. Your Hypixel key is shared with fkdr's own stats lookups, and a script's requests always go last. A script can never use up your key or slow down your lobby stats.
• Answers are kept for 10 minutes (players and guilds) and shared by every script. Looking up the same player twice, from one script or from two, sends one request. r.cached is true when the answer came from memory.
• Status and recent games only show what the player allows. Hypixel hides online status and recent games for players who turned them off in their settings. You get an empty answer for those, not an error.
• Everything is read-only. Scripts can look things up, never post, report or change anything on any service.

Look up once, keep the result

Calling a lookup from onTick is allowed and will not hurt your key, but every call still waits in your script's line. Look a player up once, keep the reply in a variable, and use it from there.

Shared scripts ask first

Your own scripts (files you wrote or put in your scripts folder yourself) use your keys without asking.

A script that is somebody else's asks once before it uses your Hypixel or Urchin key: one installed from the script portal, or a Java script that is protected or loads its code from a web address.

• The first time it looks someone up, the request waits and chat tells you the script is asking. Open the Scripts tab: the script shows Allow and Deny for that service.
• It asks once per service. Allowing Hypixel does not allow Urchin.
• Your answer is remembered. You can take it back on the script's page in the Scripts tab, or with /fkdr script revoke <name>, and the script asks again next time.
• Until you answer, its lookups come back with waiting. After Deny they come back with denied. The script keeps running either way.
• Aurora and the Hypixel answers that need no key never ask.

A script can check where it stands with fkdr.hypixel.permission() and fkdr.urchin.permission():

value	meaning
own	your own script; it never asks
allowed	you said yes
denied	you said no
ask	you have not answered yet

Writing a script for the portal

Expect waiting and denied and say something useful when you get them, for example "Allow Hypixel lookups for this script in the Scripts tab." r.message already says this, so printing it is enough.