RunicGateway/servuo-plugins
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

feat(asset-bridge): item and land art on demand, hued where the files are (Phase 5)

Browse Source 
The body catalogue is a set; this is not. This client addresses 49,152 static
ids and has art for 39,189 of them, plus 4,244 land tiles of 16,384 -- and hues
multiply the statics by three thousand. So there is no manifest and no scan:
`assets.fetch` grows two more families (`static`, `land`) and answers the keys
the website's own data names.

`assets.fetch` becomes shared plumbing. BridgeAssets now owns the command, does
the reqId/consent/key-ceiling checks once, derives the family from the keys
themselves (§5 made the key the address; a request that also named its family
would have two places to be wrong and one of them silent) and dispatches to the
reader that registered it. A batch must be of one family, because the reply
carries one `catalog` id. `assets.sources` gains `families` -- additive, so the
protocol stays 8, and EXTRACTOR_VERSION stays 2 because no existing key's bytes
change.

Two traps, both in §4.5's family -- a confident, plausible, wrong picture:

- `Art.GetStatic` memoises into a static Bitmap[0xFFFF] and hands back the SAME
  instance, while `Hue.ApplyTo` repaints in place. Hue a static once and the
  plain key comes back hued from then on, and the next hue stacks on the last.
  Measured on this client before the fix. `Files.CacheData` is now off for the
  life of the process; `TryHue` re-checks it and refuses rather than risk it,
  and the same flag decides whether a bitmap is ours to dispose.

- `PartialHue` decides whether a hue repaints every pixel or only the grey ones,
  per item id, out of `tiledata.mul` -- 13,259 of 65,536 ids on this client.
  Item 597 is a wooden screen with painted flowers: one mode reddens the
  flowers, the other the whole screen. Both decode. The first cut of this reader
  bound `TileData` to ServUO's OWN `Server.TileData` (the enclosing namespace
  beats `using Ultima;`, and it has a PartialHue flag too), which compiled and
  refused every hued key at runtime. Every such type is spelled `Ultima.` now.

Land takes no hue segment: the mode that decides how is an item flag and land
has no equivalent, so `land/3/h33` is refused rather than guessed. `h0` is not a
key either -- hue 0 means "not hued", and the plain key already names it.

Measured through the reader over the whole range: 39,189 statics and 4,244 land
tiles served, and the only refusals are the 9,963 + 12,140 empty index slots
§4.5 predicted. Nothing that carries art is refused.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
This commit is contained in:
claude
2026-09-11 05:58:45 -05:00
parent 452be696df
commit 1be1f24562
5 changed files with 1187 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

842
overlay/Scripts/Custom/Bridge/BridgeArt.cs Normal file
View File

@@ -0,0 +1,842 @@
using System;
using System.Collections.Generic;
using System.Drawing;
using System.Globalization;
using System.IO;
using System.Text;
using Ultima;
namespace Server.Custom.Bridge
{
/// <summary>
/// **Item and land art, on demand** (docs/link/v8.md §5, §11 — protocol 8, phase 5).
///
/// The body catalogue is a *set*: 1,022 sprites, enumerated, hashed and imported in one
/// pass because a bestiary needs all of them. This is the opposite shape. This client
/// addresses **49,152 static ids** and has real art for **39,189** of them, plus 4,244 land
/// tiles of 16,384 — and then there are hues, which multiply the statics by three thousand.
/// Nothing enumerates that. So there is no manifest here and no scan: the website asks for
/// the handful of keys its own data actually names, and this answers them.
///
/// (49,152 rather than the 81,884 entries `artidx.mul` declares: <c>FileIndex</c> sizes its
/// table from the **length argument it is constructed with**, `0x10000`, not from the idx
/// file — so the addressable range is `0x10000 - 0x4000`. Reading the ceiling off the file
/// instead would invent 16,348 ids, every one of them answered out of an array nobody
/// bounded.)
///
/// ── **The keys** (§5) ──
///
/// <code>
/// static/3922 one item graphic, as the client files hold it
/// static/3922/h33 the same graphic with hue 33 applied
/// land/3 one land tile
/// </code>
///
/// ── **Why the hue is applied HERE and not on the website** ──
///
/// Because it cannot be applied correctly anywhere else, and the incorrect version looks
/// fine.
///
/// A hue is not a tint. It is a 32-entry colour ramp out of `hues.mul` indexed by a
/// pixel's own red channel — and whether it replaces *every* pixel or only the grey ones
/// is decided by the <c>PartialHue</c> flag in <c>tiledata.mul</c>, per item id. On this
/// client **13,259 of 65,536 item ids carry that flag**. Get it wrong on one of them and
/// you do not get an error: item 597 is a wooden screen with painted flowers, and hued red
/// the right way the flowers turn red, the wrong way the whole screen turns red. Both
/// decode. Both are the right size. One is wrong.
///
/// The website has neither file and never will — shipping `Hues.mul` semantics and a
/// 65,536-row flag table into Node to answer a question the shard can answer for free is
/// the same trade §2.1 already refused. So hue is part of the key, and the key is resolved
/// where the files are.
///
/// ── **The trap this phase existed to find** ──
///
/// <c>Art.GetStatic</c> memoises into a static <c>Bitmap[0xFFFF]</c> and returns **the same
/// instance** every time; <c>Hue.ApplyTo</c> repaints a bitmap **in place**. Hue a static
/// once and the library's own copy is hued from then on — the plain key comes back hued,
/// and the next hue stacks on the last. It is §4.5's failure mode (a confident, plausible,
/// wrong picture that every success count agrees with) reached through a door §4.5 never
/// looked at, because phase 0 was auditing *records* and this is the library's *cache*.
///
/// <see cref="BridgeAssets.Initialize"/> turns <c>Files.CacheData</c> off for the life of
/// the process, which makes every bitmap this file receives its own. That invariant is
/// load-bearing enough that <see cref="Render"/> **re-checks it** before applying a hue and
/// refuses rather than risk it: an invariant nothing verifies is a comment.
///
/// ── **What is validated, and against what** ──
///
/// Everything §4.5 built, reused as-is. An index entry is judged before the id is handed to
/// <c>Ultima</c> (<see cref="BridgeAssetValidator.CheckEntry"/>), a static's record header
/// and row table are walked bounded (<c>StaticSane</c>), a land record is checked against
/// the 2,024 bytes <c>LoadLand</c> reads whatever the length says (<c>LandLengthSane</c>),
/// and the bound is taken against **whichever file <c>FileIndex</c> actually opened** —
/// <c>artLegacyMUL.uop</c> on every current client, never <c>art.mul</c> (§4.6).
///
/// Two of §4.5's measurements are this family's, not the catalogue's, and they are the
/// reason all of it is here: on a **stock** client **9,963 static ids and 12,140 land ids**
/// have an index entry reading `lookup 0, length 0`, which <c>FileIndex.Seek</c> treats as
/// a hit and the decoder answers with whatever was decoded last. Measured through this
/// reader over the whole range, those are the ONLY refusals — every one of the 39,189
/// statics and 4,244 land tiles that carries art is served, which is the half of the
/// measurement that says the boundary is in the right place (§4.5).
/// </summary>
public static class BridgeArt
{
/// <summary>Item graphics. <c>static/&lt;id&gt;</c>, optionally <c>/h&lt;hue&gt;</c>.</summary>
private const string StaticFamily = "static";
/// <summary>Land tiles. <c>land/&lt;id&gt;</c>, and no hue segment — see <see cref="TryParseKey"/>.</summary>
private const string LandFamily = "land";
/// <summary>The art index addresses land at its own id and statics at <c>0x4000 + id</c>.</summary>
private const int StaticBase = 0x4000;
/// <summary>Land is addressed with <c>index &amp; 0x3FFF</c> by the library itself.</summary>
private const int LandCount = 0x4000;
/// <summary><c>hues.mul</c> holds 3,000 slots; the wire's hue 1 is slot 0.</summary>
private const int MaxHue = 3000;
public static void Initialize()
{
if (!BridgeConfig.Enabled)
return;
BridgeAssets.RegisterFamily(StaticFamily, ReplyFetch);
BridgeAssets.RegisterFamily(LandFamily, ReplyFetch);
}
// ── the cache (§11) ──────────────────────────────────────────────────────────────────
private sealed class Rendered
{
public string Key;
public string Status;
public string Reason;
public string Sha256;
public byte[] Png;
public int Width;
public int Height;
public int Hue;
public bool PartialHue;
public string Source;
public int Weight
{
get { return Png == null ? 128 : Png.Length + 128; }
}
}
private sealed class Cache
{
public string Id;
public readonly Dictionary<string, Rendered> ByKey =
new Dictionary<string, Rendered>(StringComparer.Ordinal);
/// <summary>Insertion order, for eviction. See <see cref="Remember"/>.</summary>
public readonly Queue<string> Order = new Queue<string>();
public long Bytes;
public DateTime LastUsed;
}
private static readonly object _sync = new object();
private static Cache _cache;
private static readonly TimeSpan IdleFor = TimeSpan.FromMinutes(5);
// ── assets.fetch, the static and land half ───────────────────────────────────────────
/// <summary>
/// Both families' answer to <c>assets.fetch</c>. The correlation id, the operator's
/// consent, the key ceiling and the family decision were made by
/// <see cref="BridgeAssets.OnFetch"/>; every key here belongs to this reader.
///
/// The paging envelope, the byte budget and the `catalog` guard are §3.4's and
/// phase 3's, unchanged — a caller that already walks the body catalogue walks this
/// with the same loop.
/// </summary>
private static void ReplyFetch(string reqId, List<string> keys, string expected, string cursor)
{
string imagingReason;
if (!BridgeAssets.ImagingOk(out imagingReason))
{
// §17.9: a flat refusal, not a partial answer. Every picture in this family needs
// a decoder that goes through GDI+, so there is no half of it to serve.
BridgeAssets.Fail(reqId, "UNAVAILABLE",
"this shard host cannot render images - Mono's System.Drawing needs "
+ "libgdiplus. (" + imagingReason + ")");
return;
}
string id = SourceId();
if (expected != null && expected != id)
{
BridgeAssets.Fail(reqId, "UNREADABLE",
"the shard's client files changed since that catalogue was read (catalog "
+ expected + " is now " + id + "); ask again");
return;
}
Cache cache;
lock (_sync)
{
if (_cache == null || _cache.Id != id)
_cache = new Cache { Id = id };
cache = _cache;
cache.LastUsed = DateTime.UtcNow;
}
int from = ParseKeyCursor(cursor);
var sb = BridgeJson.Begin("assets.fetch.ok");
sb.Str("reqId", reqId)
.Str("family", BridgeAssets.FamilyOfKey(keys[0]))
.Str("catalog", cache.Id)
.Num("extractorVersion", BridgeAssets.EXTRACTOR_VERSION)
.Num("asked", keys.Count)
.Num("from", from);
var page = new BridgeAssets.PageBuilder(sb, "rows", BridgeConfig.AssetBatchBytes);
using (var readers = new Readers())
{
for (int i = from; i < keys.Count; i++)
{
string row = Row(cache, readers, keys[i]);
if (!page.TryAdd(row, "k:" + (i + 1).ToString(CultureInfo.InvariantCulture)))
break;
}
}
page.Close();
sb.Num("sent", page.Count);
BridgeLink.Emit(sb.End());
Sweep();
}
/// <summary>
/// One key to one JSON row.
///
/// A key this shard cannot serve is a **row**, never a failed request: an item id with
/// no art must not cost the other three hundred on the page. The three outcomes are the
/// ones phase 3 defined, and this family adds a `reason` beside them — additive, and
/// the only way an operator learns that eight of their records are damaged rather than
/// simply absent, which is a difference §4.5 spent a whole phase establishing.
/// </summary>
private static string Row(Cache cache, Readers readers, string key)
{
Rendered item = Resolve(cache, readers, key);
var sb = new StringBuilder(2048);
sb.Append("{\"key\":");
BridgeJson.Text(sb, key);
sb.Append(",\"status\":\"").Append(item.Status).Append('"');
if (item.Reason != null)
{
sb.Append(",\"reason\":");
BridgeJson.Text(sb, item.Reason);
}
if (item.Status != "ok")
{
sb.Append('}');
return sb.ToString();
}
sb.Append(",\"sha256\":\"").Append(item.Sha256).Append('"');
sb.Append(",\"bytes\":").Append(item.Png.Length.ToString(CultureInfo.InvariantCulture));
sb.Append(",\"width\":").Append(item.Width.ToString(CultureInfo.InvariantCulture));
sb.Append(",\"height\":").Append(item.Height.ToString(CultureInfo.InvariantCulture));
if (item.Hue > 0)
{
sb.Append(",\"hue\":").Append(item.Hue.ToString(CultureInfo.InvariantCulture));
sb.Append(",\"partialHue\":").Append(item.PartialHue ? "true" : "false");
}
sb.Append(",\"source\":\"").Append(item.Source).Append('"');
sb.Append(",\"png\":\"").Append(Convert.ToBase64String(item.Png)).Append("\"}");
return sb.ToString();
}
private static Rendered Resolve(Cache cache, Readers readers, string key)
{
lock (_sync)
{
Rendered cached;
if (cache.ByKey.TryGetValue(key, out cached))
return cached;
}
Rendered item;
try
{
item = Render(readers, key);
}
catch (Exception e)
{
Console.WriteLine("[Bridge] art: {0}: {1}: {2}", key, e.GetType().Name, e.Message);
item = new Rendered
{
Key = key,
Status = "absent",
Reason = e.GetType().Name
};
}
if (item.Status == "ok")
Remember(cache, item);
return item;
}
/// <summary>
/// Holds the encoded bytes against a byte budget, evicting oldest-first.
///
/// **Oldest-first rather than least-recently-used, deliberately.** The access pattern
/// this serves is a warm pass: the website asks for the keys it has never held, stores
/// them permanently, and does not ask again. What this cache is actually for is the
/// second page of a batch, a retry after a 425, and the same picture appearing in two
/// of a page's rows — all of which insertion order serves exactly as well as recency,
/// and with no bookkeeping on the hot path. A cache whose hit pattern has no recency in
/// it should not pretend to rank by it.
///
/// Only successes are held. An absent key costs one index lookup, which is cheaper than
/// the dictionary entry that would remember it.
/// </summary>
private static void Remember(Cache cache, Rendered item)
{
lock (_sync)
{
if (cache.ByKey.ContainsKey(item.Key))
return;
cache.ByKey[item.Key] = item;
cache.Order.Enqueue(item.Key);
cache.Bytes += item.Weight;
while (cache.Bytes > BridgeConfig.AssetArtCacheBytes && cache.Order.Count > 0)
{
string oldest = cache.Order.Dequeue();
Rendered evicted;
if (!cache.ByKey.TryGetValue(oldest, out evicted))
continue;
cache.ByKey.Remove(oldest);
cache.Bytes -= evicted.Weight;
}
}
}
// ── decode ───────────────────────────────────────────────────────────────────────────
/// <summary>
/// Validate, decode, hue, encode. In that order, and the order is the point.
/// </summary>
private static Rendered Render(Readers readers, string key)
{
bool land;
int id, hue;
if (!TryParseKey(key, out land, out id, out hue))
return Unsupported(key, "not a key this shard serves");
FileIndex index = readers.Index;
if (index == null || index.Index == null)
return Absent(key, "this shard has no art file");
int at = land ? id : StaticBase + id;
if (at < 0 || at >= index.Index.Length)
return Unsupported(key, "id " + id + " is past the end of this client's art index");
string reason;
BridgeAssetValidator.Verdict verdict =
BridgeAssetValidator.CheckEntry(index, at, readers.DataLength, readers.VerdataLength, out reason);
if (verdict == BridgeAssetValidator.Verdict.Absent)
{
// The 9,962 statics and 12,140 land tiles of §4.5: an index entry that reads
// `lookup 0, length 0`, which the library treats as a hit and answers with the
// previous asset's pixels. Absent is the true answer and the only safe one.
return Absent(key, reason);
}
if (verdict != BridgeAssetValidator.Verdict.Ok)
{
// A damaged record rather than a missing one. Still absent to the website — there
// is no picture either way — but the reason is worth carrying, because this one an
// operator can act on.
Console.WriteLine("[Bridge] art: {0} refused: {1}", key, reason);
return Absent(key, reason);
}
if (land)
{
if (!BridgeAssetValidator.LandLengthSane(index, at, out reason))
{
Console.WriteLine("[Bridge] art: {0} refused: {1}", key, reason);
return Absent(key, reason);
}
}
else if (readers.Reader == null || !readers.Reader.StaticSane(index, at, out reason))
{
Console.WriteLine("[Bridge] art: {0} refused: {1}",
key, reason ?? "the art record could not be read");
return Absent(key, reason ?? "the art record could not be read");
}
// A hue is resolved BEFORE anything is decoded, so a bad one costs no pixels and, more
// to the point, cannot half-apply to a picture that then gets cached and served.
Ultima.Hue applied = null;
bool partial = false;
if (hue > 0)
{
if (!TryHue(id, hue, out applied, out partial, out reason))
return Unsupported(key, reason);
}
Bitmap bitmap = land
? Art.GetLand(id)
// `checkmaxid: false` on purpose (§4.5): the default maps an out-of-range id to 0
// and returns ITEM ZERO'S PICTURE. The id is already bounded against the index
// that was actually opened, so this can only be loud.
: Art.GetStatic(id, false);
// **Whether this bitmap is ours to dispose is the same question as whether it is ours
// to hue**, and it has the same answer. With the library's cache off — which
// `BridgeAssets.Initialize` guarantees and `TryHue` re-checks — every call decodes a
// fresh instance that nothing else holds, so not disposing it would leak one bitmap per
// fetched key. With the cache on, that instance is the library's own copy and disposing
// it would leave a disposed `Bitmap` in a static array for the next caller to fault on.
// Both mistakes are silent; the flag decides, once, here.
bool owned = !Files.CacheData;
try
{
if (bitmap == null || bitmap.Width <= 0 || bitmap.Height <= 0)
return Absent(key, "the decoder returned no picture");
if (applied != null)
applied.ApplyTo(bitmap, partial);
byte[] png = BridgeAssets.BitmapToPng(bitmap);
if (png == null)
return Absent(key, "the picture could not be encoded");
return new Rendered
{
Key = key,
Status = "ok",
Sha256 = BridgeAssets.Sha256Hex(png),
Png = png,
Width = bitmap.Width,
Height = bitmap.Height,
Hue = hue,
PartialHue = partial,
Source = readers.Source
};
}
finally
{
if (owned && bitmap != null)
bitmap.Dispose();
}
}
/// <summary>
/// Resolves one wire hue onto a ramp, and decides whether it repaints the whole sprite
/// or only its grey pixels.
///
/// Four things have to hold, and every one of them has a way of not holding that
/// produces a picture rather than an error:
///
/// **The library's cache is off.** Re-checked here because <c>ApplyTo</c> repaints in
/// place: with the cache on, this would edit the copy <c>Art</c> hands to everyone
/// else. <see cref="BridgeAssets.Initialize"/> turns it off at boot and this refuses
/// if it somehow did not, because the failure is invisible and permanent.
///
/// **`hues.mul` is present.** When it is missing <c>Hues.Initialize</c> does not throw
/// — it fills all 3,000 slots with a <c>new Hue(index)</c> whose ramp is **all zeroes**,
/// and applying one of those paints the sprite black. An all-zero ramp is therefore
/// refused whatever the reason for it; on this client there are none.
///
/// **The index is in range.** The wire's hue is 1-based — <c>Ultima.Map</c> does the
/// same <c>GetHue(hue - 1)</c> at line 450 — and <c>GetHue</c> itself masks with
/// `0x3FFF` and falls back to slot 0 rather than failing, so an out-of-range hue would
/// silently become a different colour. Bound it here instead.
///
/// **The <c>PartialHue</c> flag decides the mode**, per item id, out of
/// <c>tiledata.mul</c>. This is the one that is invisible: both modes decode, both are
/// the right size, and 13,259 of this client's item ids need the grey-only one.
/// **Land has no such flag**, which is why <see cref="TryParseKey"/> does not accept a
/// hue on a land key at all rather than guessing a mode for it.
/// </summary>
private static bool TryHue(int id, int hue, out Ultima.Hue applied, out bool partial, out string reason)
{
applied = null;
partial = false;
reason = null;
if (Files.CacheData)
{
reason = "this shard's art cache is on, so a hue cannot be applied safely";
Console.WriteLine("[Bridge] art: refusing hue {0}: {1}", hue, reason);
return false;
}
if (hue < 1 || hue > MaxHue)
{
reason = "hue " + hue + " is outside 1-" + MaxHue;
return false;
}
Ultima.Hue[] list = Ultima.Hues.List;
if (list == null || hue - 1 >= list.Length || list[hue - 1] == null)
{
reason = "this client has no hue table";
return false;
}
Ultima.Hue candidate = list[hue - 1];
if (candidate.Colors == null || AllZero(candidate.Colors))
{
reason = "hue " + hue + " has no colours in this client's hues.mul";
return false;
}
if (!TryPartialHue(id, out partial, out reason))
return false;
applied = candidate;
return true;
}
private static bool AllZero(short[] colors)
{
for (int i = 0; i < colors.Length; i++)
{
if (colors[i] != 0)
return false;
}
return true;
}
/// <summary>
/// The <c>PartialHue</c> flag for one item id.
///
/// Refuses rather than defaults when <c>tiledata.mul</c> cannot be read. Defaulting
/// either way would be a coin flip on 13,259 ids, and the losing side of it is a
/// picture that looks deliberate.
///
/// **Every type here is spelled <c>Ultima.</c> on purpose, and it is not style.**
/// ServUO declares its own <c>Server.TileData</c>, <c>Server.ItemData</c> and
/// <c>Server.TileFlag</c> — with a <c>PartialHue</c> member — in
/// <c>Server/TileData.cs</c>. This file lives in <c>Server.Custom.Bridge</c>, so the
/// enclosing namespace beats the <c>using Ultima;</c> and the unqualified spelling
/// silently binds to the *server's* table: it compiles, the flag exists, and the answer
/// comes from a file resolved through <c>Core.DataDirectories</c> rather than through
/// <c>Ultima.Files</c>, which is the one thing §4.6 says never to do — decide a picture
/// with a file other than the one the pixels came out of. The first run of this reader
/// did exactly that and refused every hued key with a <c>TypeInitializationException</c>
/// from a class this code never meant to name.
/// </summary>
private static bool TryPartialHue(int id, out bool partial, out string reason)
{
partial = false;
reason = null;
Ultima.ItemData[] table;
try
{
table = Ultima.TileData.ItemTable;
}
catch (Exception e)
{
reason = "this client's tiledata could not be read (" + e.GetType().Name + ")";
return false;
}
if (table == null || id < 0 || id >= table.Length)
{
reason = "this client's tiledata does not describe item " + id;
return false;
}
partial = (table[id].Flags & Ultima.TileFlag.PartialHue) != 0;
return true;
}
private static Rendered Absent(string key, string reason)
{
return new Rendered { Key = key, Status = "absent", Reason = reason };
}
private static Rendered Unsupported(string key, string reason)
{
return new Rendered { Key = key, Status = "unsupported", Reason = reason };
}
// ── keys, cursors and the source id ──────────────────────────────────────────────────
/// <summary>
/// <c>static/&lt;id&gt;</c>, <c>static/&lt;id&gt;/h&lt;hue&gt;</c> and
/// <c>land/&lt;id&gt;</c>.
///
/// **A land key takes no hue segment.** The client can hue a land tile, but the mode
/// that decides how is an *item* flag and land has no equivalent — so the honest answer
/// to `land/3/h33` is that this shard does not serve it, rather than a picture produced
/// by guessing. Nothing on the wire carries a hued land tile today; if something ever
/// does, it arrives with a reason to choose.
/// </summary>
private static bool TryParseKey(string key, out bool land, out int id, out int hue)
{
land = false;
id = 0;
hue = 0;
if (key == null)
return false;
string[] parts = key.Split('/');
if (parts.Length < 2 || parts.Length > 3)
return false;
if (parts[0] == LandFamily)
land = true;
else if (parts[0] != StaticFamily)
return false;
if (!Int32.TryParse(parts[1], NumberStyles.None, CultureInfo.InvariantCulture, out id))
return false;
if (id < 0)
return false;
if (land && id >= LandCount)
return false;
if (parts.Length == 2)
return true;
if (land)
return false;
string segment = parts[2];
if (segment.Length < 2 || segment[0] != 'h')
return false;
if (!Int32.TryParse(segment.Substring(1), NumberStyles.None,
CultureInfo.InvariantCulture, out hue))
return false;
// **`h0` is not a key.** Hue 0 on the wire means "this item is not hued", so the plain
// key already names its picture. Accepting `static/3922/h0` as a synonym would have
// the website store the identical PNG twice under two names, diff them separately on
// every Update, and show whichever row it happened to join against -- for a distinction
// that does not exist. The caller drops the segment instead.
return hue > 0;
}
private static int ParseKeyCursor(string cursor)
{
if (cursor == null)
return 0;
int value;
if (cursor.StartsWith("k:", StringComparison.Ordinal)
&& Int32.TryParse(cursor.Substring(2), NumberStyles.None, CultureInfo.InvariantCulture, out value))
return Math.Max(0, value);
return 0;
}
/// <summary>
/// Everything that decides these bytes, hashed into one short id — the same guard
/// phase 3 built, over this family's inputs.
///
/// Four files, and each earns its place: the art data file holds the pixels,
/// `hues.mul` holds the ramps, `tiledata.mul` decides which of the two hue modes an
/// item gets, and `verdata.mul` can patch any record in any of them. Leaving
/// `tiledata.mul` out would be the subtle one — a client patch that only flipped
/// <c>PartialHue</c> flags changes no pixel in any source file and every hued picture
/// derived from them.
/// </summary>
private static string SourceId()
{
var sb = new StringBuilder(256);
sb.Append(BridgeAssets.EXTRACTOR_VERSION);
foreach (string path in new[]
{
BridgeAssetValidator.ArtDataPath(),
FilePath("hues.mul"),
FilePath("tiledata.mul"),
FilePath("verdata.mul")
})
{
sb.Append('|');
if (path == null)
continue;
try
{
var info = new FileInfo(path);
if (!info.Exists)
continue;
sb.Append(info.Length).Append(',').Append(info.LastWriteTimeUtc.Ticks);
}
catch
{
// An unreadable file is itself a state, and one that must not change from page
// to page without being noticed. Leaving the slot empty does that.
}
}
return BridgeAssets.Sha256Hex(Encoding.UTF8.GetBytes(sb.ToString())).Substring(0, 16);
}
private static string FilePath(string name)
{
try
{
return Files.GetFilePath(name);
}
catch
{
return null;
}
}
// ── shared plumbing ──────────────────────────────────────────────────────────────────
/// <summary>
/// The art index and its record reader, opened for one reply and closed with it — the
/// same lifetime rule phase 3's <c>Readers</c> follows, and for the same reason: a page
/// decodes hundreds of sprites through them and opening them is microseconds, so
/// holding handles on the operator's client files for the life of a cache buys nothing.
/// </summary>
private sealed class Readers : IDisposable
{
public readonly FileIndex Index;
public readonly BridgeAssetValidator.RecordReader Reader;
public readonly long DataLength;
public readonly long VerdataLength;
/// <summary>
/// Which file the pixels came out of — `uop` or `legacy` — carried on every row
/// beside the body catalogue's own `source` (§4.9). On this plane it answers §4.6's
/// operator question: art added to `art.mul` while `artLegacyMUL.uop` is present is
/// never read, and a row that says `uop` is what says so.
/// </summary>
public readonly string Source;
public Readers()
{
string data = BridgeAssetValidator.ArtDataPath();
string verdata = FilePath("verdata.mul");
DataLength = BridgeAssetValidator.MulLength(data);
VerdataLength = BridgeAssetValidator.MulLength(verdata);
Source = data != null && data.EndsWith(".uop", StringComparison.OrdinalIgnoreCase)
? "uop"
: "legacy";
try
{
Index = BridgeAssetValidator.OpenArtIndex();
if (data != null)
Reader = new BridgeAssetValidator.RecordReader(data, verdata);
}
catch (Exception e)
{
Console.WriteLine("[Bridge] art: could not open the art files: {0}", e.Message);
}
}
public void Dispose()
{
if (Reader == null)
return;
try
{
Reader.Dispose();
}
catch
{
// Closing a read-only handle. Nothing useful is left to do.
}
}
}
/// <summary>
/// Lets the held pictures go once nothing has asked for one in five minutes. The id is
/// derived from the client files rather than minted per build, so a walk that spans the
/// drop resumes against the same catalogue instead of starting over.
/// </summary>
private static void Sweep()
{
lock (_sync)
{
if (_cache == null)
return;
if (DateTime.UtcNow - _cache.LastUsed > IdleFor)
_cache = null;
}
}
public static string Status()
{
lock (_sync)
{
if (_cache == null)
return "art(empty)";
return String.Format("art(id={0} held={1} bytes={2} cap={3})",
_cache.Id, _cache.ByKey.Count, _cache.Bytes, BridgeConfig.AssetArtCacheBytes);
}
}
}
}