Home

Welcome to the documentation space for GOKZ.TOP

Release notes for the website are available from the version label in the app sidebar.

External websites can add a Play replay link that opens a public GOKZ replay directly in the hosted viewer. Build https://replays.gokz.top/, then set its replay_url search parameter to the replay's absolute HTTPS download URL with URL.searchParams.set; this safely performs the required percent encoding. The download endpoint must accept an unauthenticated GET, return the raw supported .replay file, and allow browser CORS access from https://replays.gokz.top (or use Access-Control-Allow-Origin: * for a fully public file), including after redirects. Do not place credentials or secret signed values in this parameter because it appears in browser history and access logs. The viewer uses its own hosted map exports, so the replay's map must already be available there. replay_url is mutually exclusive with the viewer's replay and jump_id parameters.

Root admins can use /admin/settings to place the Discord community link in either the navbar or the footer.

Root admins can also enable or disable GlobalAPI record imports for the current deployment from /admin/settings. The setting defaults to enabled; disable it on staging to avoid duplicate sync work. Re-enabling it resumes imports on the next scheduler check, while other GlobalAPI synchronization tasks remain active.

Players can generate a short-lived 27-character QQ binding code from /settings/binding-code and send /bind <code> to the QQ bot to link their Steam account. Before this works, a root admin must open /admin/settings, generate the QQ binding secret, and copy it into the bot's local verifier. The website does not store QQ bindings. The same secret authenticates trusted bot API requests, including map ratings submitted for a bound player. Rotating or revoking the secret immediately invalidates all outstanding codes and bot API access; update the bot whenever you rotate it.

Verified social links can be toggled in /settings/social-links to show or hide their streams and videos on GOKZ.TOP. Hidden links remain visible on player profiles and their media continues to be tracked, but hidden links are excluded from the public media feed and live-stream polling.

Player names, avatars, countries, and Steam custom IDs now refresh automatically in the background when a displayed profile has not been initialized from Steam or is more than seven days old.

When signed-in players open their own /profile/:identifier/runs page, new records appear automatically without requiring a page refresh. The live connection is filtered to that player's Steam account and the currently selected scope. WR times are blue for zero-teleport winning runs and yellow for winning runs with teleports, including zero-teleport winners displayed in the NUB bucket. The Show WR time and Show WR gap preferences are remembered in first-party browser cookies.

Root admins can manage S/A/B/C tournaments and assign placements one through four. Tournament end dates are optional; an omitted end date creates a one-day tournament. Player profiles show the resulting tournament achievement badges: gold for champions, silver for second place, and bronze for third or fourth place.

Map detail pages now include a WR History tab. It shows only main-course runs that established a new world record, with scope and NUB/PRO filters and holder-colored timeline segments.

The Dashboard now opens on /dashboard/wrs. Its uncapped cache is initially seeded from current 1000-point PB winners, then each newly established WR is added without removing the WR it superseded. The page combines NUB and PRO achievements when the same zero-teleport run earns both, and displays the run time, gap, and previous holder over the map image. Map and tier filters sit alongside a NUB/PRO view toggle and the site-wide scope selector; switching views does not remove either achievement from a combined WR card. The page loads 20 cards initially and automatically loads more in 20-card batches while scrolling, up to a frontend-only limit of 100. Live updates refresh the first batch and safely reset loaded later batches when a new WR changes the start of the feed.

The /maps page defaults to Best Rated sorting. This confidence-adjusted score combines each map's Overall average and review count with the platform-wide average using a six-review prior: (reviews * map average + 6 * global average) / (reviews + 6). The raw Overall average remains visible and available as a separate sort.

Competitive decimal ratings are displayed by flooring at their shown precision, so the displayed value never exceeds the underlying value. Player ratings and adjusted map ratings show two decimal places, while map review averages show one. Sorting, filtering, rating levels, and rating-ladder positions continue to use the unchanged underlying values.

Map skill breakdowns on /maps come from analysis imported into the backend. Maps without imported analysis display 100% Unknown. Operators can load a version 3 analysis file manually from the backend directory with python -m app.import_map_skills /path/to/index.json; the normal maps API returns aggregate skill fractions but keeps ordered analysis segments private for future features.

Server operators can install gokz-top-ljroom to teleport players to long-jump blocks detected by the map analyzer. The plugin downloads the current map's room and slot coordinates from GOKZ.TOP when the map starts. Use !lj [distance] or !ljroom [distance] to teleport to the exact or nearest available block, and !ljdefault <distance> to save a preferred default. As with GOKZ's !goto, an enabled safeguard blocks teleporting during a valid run. Otherwise, a running timer is stopped before teleporting. Backend operators refresh this data manually with python -m app.import_lj_rooms /path/to/gokz-lj-rooms.json; the export is not bundled with the application.

Player profiles use that analysis to show Boxtech, Strafe, BHOP, Climb, Ladder, and Slide ratings. For each skill, the strongest PB-point evidence is weighted by the map's skill portion and calibrated independently against eligible players in the selected scope. The profile currently uses a relative radar that preserves the strongest skill's global size while magnifying differences within the player; the numbers beside every axis remain the globally calibrated ratings. Skill ratings follow the same two-decimal floor rule as other competitive ratings, and the population-best converter value remains below 11, so its highest displayed value is 10.99. The player leaderboard has one selectable skill column for displaying and sorting by any of the six skills.

After deploying the skill-rating migration or changing the formula or imported map analysis, operators must explicitly rebuild raw skill ratings and save fresh converters for all four scopes: OVR, KZT, SKZ, and VNL. From the backend environment, run kztop build skill-ratings to rebuild all scopes, inspect kztop build skill-converters to preview their distributions, then run kztop build skill-converters --save after review. API reads and nightly leaderboard rebuilds do not recalibrate these percentile curves automatically.

The /servers page now shows a GlobalAPI status badge on each live server map. The badge reports the server's gokz-global checks against GlobalAPI; hover it to see the API key, plugin, settings, map, and KZT/SKZ/VNL mode results. Player validity is not evaluated because it is player-specific. Server details also show player ping and the server's net-graph-style SV and VAR frame metrics when a recent gokz-top-servers heartbeat provides them; servers running older plugin versions continue to work without these fields.

Server operators can set each server's Visibility to Public or Hidden from /admin/servers/public-server. Visibility is separate from the Enabled, Invalid, and Disabled health statuses. Hidden servers keep sending heartbeats and being health-checked, but they are excluded from the public server browser, server details, history, group counts, and live updates.

Server whitelist integrations can query GET /v1/servers/{server_id}/players/{identifier}/activity-summary. first_seen_at is the time when the player created their first record on any server, while first_server_record_at is their first record on the requested server group. active_days counts unique UTC calendar days with a record on that server group. Pass recent_days=365 to count only records created during the 365-day interval ending at generated_at; omit it for the all-time count. The separate recent_hours parameter controls only the record-time window used by recent_playtime.

Server operators can also select one or more owned GlobalAPI servers on /admin/servers/globalapi-server and choose Export records. The downloaded .sql.gz file is a streamed MySQL import for the standard GOKZ LocalDB Players, Maps, MapCourses, and Times tables. It exports valid VNL, SKZ, and KZT records, converts SteamID64 values and run times to GOKZ's local formats, preserves existing player and map rows, and appends times. Import the file only once into a database whose GOKZ LocalDB tables already exist, for example with gzip -dc gokz-localdb-records-*.sql.gz | mysql -u USER -p DATABASE. Take a database backup first; importing the same file again appends duplicate times.

Backend operators can create a fuller compressed CSV archive with kztop export records --server-id 1683 --server-id 1633 --output /exports/axe-records.csv.gz, or replace the server IDs with a repeatable --server-group UUID, custom ID, or exact name. Optional inclusive --after and --before ISO 8601 bounds filter record creation time. The CSV includes valid VNL, SKZ, KZT, and NKZ records with compatible Steam IDs, permits map names of any length, preserves duplicate runs, and uses the header record_uuid,globalapi_record_id,server_id,steamid64,steamid32,player_name,player_country,map_id,map_name,stage,mode,local_mode,style,runtime_seconds,runtime_ms,teleports,created_at,updated_at,replay_id,is_valid. Player aliases take precedence over original names. The command refuses to replace an existing file unless --force is supplied and prints counts for exported and excluded rows.

Use kztop export players with the same server/group, date, output, and overwrite options to export the distinct compatible players represented by those valid records. Its compressed CSV header is steamid32,steamid64,alias,cheater,ip,last_played_at,country,created_at. The display alias falls back to the Steam name, cheater is 1 only when a permanent ban exists, and the IP comes from the player's newest session across every server. First and last activity combine the selected server records with the player's earliest connection and latest completed-session disconnect across every server.

The /leaderboards/countries page ranks countries by the average rating of their ten highest-rated eligible players. It shows ranked-player and 30-day active-player counts, each country's top three players, and median rating. Countries with fewer than ten eligible players remain visible but do not receive a rank.

The /compare page compares two players in the currently selected scope. Use player search to choose either side, or right-click another player while signed in and select Compare to open a comparison against your own account. The page shows rating, global rating rank, points, Rating E/H, WR and high-value PB totals, tier-by-tier main-map completion, and NUB/PRO main-stage PBs. Bonus stages and invalidated maps are excluded; run rows are ordered by Player 1's PB points and can be limited to maps both players finished.

The /media page includes only KZ-related uploads from verified YouTube and Bilibili accounts. An upload qualifies when an exact platform tag is KZ, GOKZ, Kreedz, or CS2KZ; when one of those terms appears as a standalone term in its title or description; or when its title or description contains a standalone map-shaped token beginning with kz_, bkz_, kzpro_, or xc_. Map-shaped names do not have to exist in the current map catalog. Nonmatching uploads stay in the internal cache for the normal 90-day retention period so later metadata edits can make them eligible, but they are not shown publicly and their thumbnails are not cached in R2.

Operators can set the server-only BILIBILI_COOKIE environment variable to a dedicated Bilibili browser cookie containing SESSDATA; this lets the upload poller recover from Bilibili anti-bot checks. Do not use a personal account cookie or expose this value to browsers. After deploying the media-classification migration, run kztop sync media --reclassify-existing in staging and then production to re-fetch canonical metadata and classify retained uploads. Use --platform, --limit, and --dry-run for controlled verification or recovery runs.

Community polls are available at /polls. Anyone can browse active and closed polls, while signed-in players can vote. Open-poll results are shown only to players who have voted; once a poll closes, results become public. Root admins manage poll creation and lifecycle from /admin/polls.