@terrafirmagreg-team/game 0.0.0-stage → 0.1.0

package/src/components/preview-icon.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { DynamicIcon, type IconName } from 'lucide-react/dynamic';
+import { EntryIcon } from '@terrafirmagreg-team/game/components/entry/icon';
+import type { ReferenceKind } from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+import type { PreviewIcon } from '@terrafirmagreg-team/ui/types/preview';
+
+export function PagePreviewIcon({ icon }: { icon: PreviewIcon }) {
+  if (icon.type === 'entry') {
+    return (
+      <EntryIcon
+        reference={{ kind: icon.kind as ReferenceKind, id: icon.id }}
+        dataset={icon.dataset}
+        size={16}
+        missing="placeholder"
+      />
+    );
+  }
+  return (
+    <DynamicIcon
+      name={icon.name as IconName}
+      className="size-4 shrink-0"
+    />
+  );
+}

package/src/hooks/use-dump-location.ts

@@ -0,0 +1,18 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+import {
+  dumpLocation,
+  subscribeDumpLocations,
+  type DumpLocation,
+} from '@terrafirmagreg-team/game/lib/dump/paths';
+
+export function useDumpLocation(
+  dataset: string | undefined,
+): DumpLocation | undefined {
+  return useSyncExternalStore(
+    subscribeDumpLocations,
+    () => (dataset ? dumpLocation(dataset) : undefined),
+    () => undefined,
+  );
+}

package/src/hooks/use-entry-context.ts

@@ -0,0 +1,35 @@
+'use client';
+
+import {
+  createContext,
+  createElement,
+  useContext,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+type EntryContextValue = {
+  dataset: string;
+  lang?: Lang;
+  langMap?: Record<string, string>;
+};
+
+const EntryContext = createContext<EntryContextValue | null>(null);
+
+export function EntryProvider({
+  dataset,
+  lang,
+  langMap,
+  children,
+}: EntryContextValue & { children: ReactNode }) {
+  const value = useMemo(
+    () => ({ dataset, lang, langMap }),
+    [dataset, lang, langMap],
+  );
+  return createElement(EntryContext.Provider, { value }, children);
+}
+
+export function useEntryContext(): EntryContextValue | null {
+  return useContext(EntryContext);
+}

package/src/hooks/use-icon-source.ts

@@ -0,0 +1,297 @@
+'use client';
+
+import { useAsyncResult } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import { useCycleIndex } from '@terrafirmagreg-team/ui/hooks/use-cycle-index';
+import {
+  classifyRefId,
+  isTagKind,
+  parseStackId,
+  tagKindOf,
+} from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+import { texturePublicUrl } from '@terrafirmagreg-team/game/lib/dump/assets/urls';
+import { useDumpLocation } from '@terrafirmagreg-team/game/hooks/use-dump-location';
+import { lookupSpriteInBundle } from '@terrafirmagreg-team/game/lib/dump/assets/atlas/lookup';
+import type { AtlasLookup } from '@terrafirmagreg-team/game/lib/dump/assets/atlas/dto';
+import {
+  blockItemId,
+  fetchAtlases,
+  fetchEntityTexture,
+  fetchTagMembers,
+  peekBlockItem,
+  peekEntityTexture,
+  peekTagMembers,
+} from '@terrafirmagreg-team/game/lib/entry/icon-load';
+import { loadClientModAtlases } from '@terrafirmagreg-team/game/lib/dump/client/atlases';
+import { stackKindOf } from '@terrafirmagreg-team/game/lib/entry/icon';
+import type {
+  DumpNbt,
+  ReferenceKind,
+  TaggedReference,
+} from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+
+export const ENTRY_CYCLE_MS = 1500;
+
+export type IconSource = {
+
+  rawId: string;
+
+  cycleRef: TaggedReference | null;
+
+  lookup: AtlasLookup | null;
+
+  missingLookup: AtlasLookup | null;
+  missingPending: boolean;
+
+  imgSrc: string | undefined;
+
+  sourceKey: string;
+
+  pending: boolean;
+  awaitingAtlas: boolean;
+  awaitingTexture: boolean;
+  usesAtlas: boolean;
+  isEntity: boolean;
+};
+
+export function useIconSource({
+  dataset,
+  reference,
+  id,
+  kind,
+  tag,
+  missing,
+  preferVariant,
+}: {
+  dataset?: string;
+  reference?: TaggedReference;
+  id?: string;
+  kind?: ReferenceKind;
+  tag?: DumpNbt;
+  missing: 'placeholder' | 'item' | 'hide';
+  preferVariant?: boolean;
+}): IconSource {
+  const ref = reference ?? (id ? classifyRefId(id, kind) : undefined);
+  const refKind = ref?.kind;
+  const rawId = ref?.id ?? id ?? '';
+  const nbt = tag ?? ref?.tag;
+  const tagMemberKind = tagKindOf(refKind);
+  const tagKey =
+    dataset && rawId && isTagKind(refKind)
+      ? `${dataset}/${tagMemberKind ?? 'item'}/${rawId}`
+      : null;
+  const tagMembersPeek = tagKey
+    ? peekTagMembers(dataset!, rawId, tagMemberKind ?? 'item')
+    : undefined;
+  const tagHit = useAsyncResult(
+    tagKey && tagMembersPeek === undefined
+      ? async () => ({
+          key: tagKey,
+          members: await fetchTagMembers(
+            dataset!,
+            rawId,
+            tagMemberKind ?? 'item',
+          ),
+        })
+      : false,
+    [dataset, rawId, tagMemberKind, tagKey, tagMembersPeek],
+  );
+  const tagMembers = !tagKey
+    ? undefined
+    : tagMembersPeek !== undefined
+      ? tagMembersPeek
+      : tagHit.pending
+        ? undefined
+        : tagHit.value?.key === tagKey
+          ? (tagHit.value.members ?? null)
+          : null;
+  const cycleRefs =
+    tagMembers && tagMembers.length > 1
+      ? tagMembers.map((member) => ({
+          kind: (tagMemberKind ?? 'item') as ReferenceKind,
+          id: member,
+        }))
+      : null;
+  const [cycleIndex] = useCycleIndex(cycleRefs?.length ?? 0, {
+    enabled: cycleRefs !== null,
+    intervalMs: ENTRY_CYCLE_MS,
+  });
+  const itemId = !rawId
+    ? ''
+    : tagKey
+      ? tagMembers === undefined
+        ? undefined
+        : tagMembers === null
+          ? null
+          : (tagMembers[0] ?? null)
+      : rawId;
+  const memberKind =
+    isTagKind(refKind) && itemId && !itemId.startsWith('#')
+      ? (tagMemberKind ?? 'item')
+      : refKind;
+  const blockKey =
+    dataset && memberKind === 'block' && itemId && !itemId.startsWith('#')
+      ? `${dataset}/${itemId}`
+      : null;
+  const blockPeek = blockKey ? peekBlockItem(dataset!, itemId!) : undefined;
+  const blockHit = useAsyncResult(
+    blockKey && blockPeek === undefined
+      ? async () => ({
+          key: blockKey,
+          id: await blockItemId(dataset!, itemId!),
+        })
+      : false,
+    [dataset, itemId, blockKey, blockPeek],
+  );
+  const blockResolved = !blockKey
+    ? undefined
+    : blockPeek !== undefined
+      ? blockPeek
+      : blockHit.pending
+        ? undefined
+        : blockHit.value?.key === blockKey
+          ? (blockHit.value.id ?? null)
+          : null;
+  const atlasId = blockKey ? (blockResolved ?? undefined) : itemId;
+  const displayKind = blockKey && blockResolved ? 'item' : memberKind;
+  const resolvedId = atlasId ?? rawId;
+  const isTexture = displayKind === 'texture';
+  const isEntity = displayKind === 'entity';
+  const parsed = parseStackId(resolvedId.replace(/^#/, ''));
+  const spriteId = parsed.id;
+  const eggId =
+    isEntity && spriteId && !spriteId.startsWith('#')
+      ? `${spriteId}_spawn_egg`
+      : undefined;
+  const usesAtlas =
+    Boolean(dataset && rawId) &&
+    (displayKind === 'item' ||
+      displayKind === 'block' ||
+      displayKind === 'fluid' ||
+      Boolean(eggId));
+  const modId = spriteId.includes(':')
+    ? spriteId.slice(0, spriteId.indexOf(':'))
+    : '';
+  const atlasNeedsLoad =
+    dataset && usesAtlas && modId && spriteId && !spriteId.startsWith('#');
+  const atlasPeek = atlasNeedsLoad
+    ? loadClientModAtlases.peek(dataset, modId)
+    : undefined;
+  const atlasBundle =
+    atlasPeek && (atlasPeek.items || atlasPeek.blocks) ? atlasPeek : null;
+  const atlases = useAsyncResult(
+    atlasNeedsLoad && atlasPeek === undefined
+      ? () => fetchAtlases(dataset, modId)
+      : false,
+    [atlasNeedsLoad, atlasPeek, dataset, modId],
+  );
+  const atlasValue = atlasPeek === undefined ? atlases.value : atlasBundle;
+  const sourceKey = `${dataset}:${displayKind}:${resolvedId}`;
+  const dumpLoc = useDumpLocation(dataset);
+  const texturePeek =
+    dataset && isTexture && rawId
+      ? texturePublicUrl(dataset, rawId)
+      : dataset && isEntity && resolvedId
+        ? peekEntityTexture(dataset, resolvedId, nbt)
+        : null;
+  const textureSrc = useAsyncResult(
+    dataset && isTexture && rawId
+      ? false
+      : dataset && isEntity && resolvedId && texturePeek === undefined
+        ? async () => ({
+            key: sourceKey,
+            url:
+              (await fetchEntityTexture(dataset, resolvedId, nbt)) ?? undefined,
+          })
+        : false,
+    [
+      isTexture,
+      isEntity,
+      dataset,
+      rawId,
+      resolvedId,
+      sourceKey,
+      nbt,
+      texturePeek,
+    ],
+  );
+  const resolvedTexture =
+    texturePeek !== undefined
+      ? (texturePeek ?? undefined)
+      : textureSrc.value?.key === sourceKey
+        ? textureSrc.value.url
+        : undefined;
+  const wantMissingItem =
+    missing === 'item' && dataset !== undefined && usesAtlas;
+  const missingPeek = wantMissingItem
+    ? loadClientModAtlases.peek(dataset, 'ftbquests')
+    : undefined;
+  const missingBundleValue =
+    missingPeek !== undefined
+      ? missingPeek.items || missingPeek.blocks
+        ? missingPeek
+        : null
+      : undefined;
+  const missingBundle = useAsyncResult(
+    wantMissingItem && missingPeek === undefined
+      ? () => fetchAtlases(dataset, 'ftbquests')
+      : false,
+    [wantMissingItem, missingPeek, dataset],
+  );
+  const missingLookup = wantMissingItem
+    ? lookupSpriteInBundle(
+        missingBundleValue === undefined
+          ? missingBundle.value
+          : missingBundleValue,
+        {
+          id: 'ftbquests:missing_item',
+          kind: 'item',
+        },
+      )
+    : null;
+
+  const lookupKind = stackKindOf(displayKind) ?? (eggId ? 'item' : undefined);
+  const lookup = usesAtlas
+    ? lookupSpriteInBundle(
+        atlasValue,
+        {
+          id: eggId ?? spriteId,
+          ...(lookupKind ? { kind: lookupKind } : {}),
+          ...(nbt !== undefined
+            ? { tag: nbt }
+            : parsed.nbt !== undefined
+              ? { tag: parsed.nbt }
+              : {}),
+        },
+        lookupKind,
+        preferVariant,
+      )
+    : null;
+  const pending =
+    (isTagKind(refKind) && itemId === undefined) ||
+    (blockKey !== null && blockResolved === undefined);
+  const awaitingAtlas =
+    usesAtlas &&
+    atlasId != null &&
+    !atlasId.startsWith('#') &&
+    atlases.pending;
+  const awaitingTexture =
+    (isTexture || isEntity) &&
+    texturePeek === undefined &&
+    (textureSrc.pending || (isTexture && !dumpLoc));
+
+  return {
+    rawId,
+    cycleRef:
+      cycleRefs && !pending ? (cycleRefs[cycleIndex] ?? cycleRefs[0]!) : null,
+    lookup: lookup ?? null,
+    missingLookup: missingLookup ?? null,
+    missingPending: missingBundle.pending,
+    imgSrc: isTexture || isEntity ? resolvedTexture : undefined,
+    sourceKey,
+    pending,
+    awaitingAtlas,
+    awaitingTexture,
+    usesAtlas,
+    isEntity,
+  };
+}

package/src/hooks/use-lang-map.ts

@@ -0,0 +1,18 @@
+'use client';
+
+import { useAsyncResult } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import { dumpReader } from '@terrafirmagreg-team/game/lib/dump/reader';
+
+export function useLangMap(
+  dataset: string | undefined,
+  lang: string | undefined,
+  enabled = true,
+): Record<string, string> | undefined {
+  const { value, pending } = useAsyncResult(
+    enabled && dataset && lang
+      ? () => dumpReader(dataset).then((reader) => reader.getLang(lang))
+      : false,
+    [dataset, lang, enabled],
+  );
+  return pending ? undefined : value;
+}

package/src/lib/dump/assets/atlas/dto.ts

@@ -0,0 +1,49 @@
+import type { DumpNbt, TaggedReference } from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+
+export type AtlasPage = {
+  image: string;
+  w: number;
+  h: number;
+};
+
+export type AtlasTint = 'none' | 'grass' | 'foliage' | 'water' | 'custom';
+
+export type AtlasSprite = {
+  ref: TaggedReference;
+  page: number;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  tint?: AtlasTint;
+  tintColor?: string;
+  langKey?: string;
+};
+
+export type AtlasKind = 'item' | 'block';
+
+export type IconAtlas = {
+  sprites: AtlasSprite[];
+  pages: AtlasPage[];
+  modId: string;
+  dataset: string;
+  kind: AtlasKind;
+};
+
+export type AtlasBundle = {
+  items: IconAtlas | null;
+  blocks: IconAtlas | null;
+};
+
+export type SpriteQuery = {
+  kind?: 'item' | 'block' | 'fluid';
+  id: string;
+  tag?: DumpNbt;
+};
+
+export type AtlasLookup = {
+  atlas: IconAtlas;
+  sprite: AtlasSprite;
+  page: AtlasPage;
+  spriteId: string;
+};

package/src/lib/dump/assets/atlas/lookup.ts

@@ -0,0 +1,206 @@
+import type {
+  AtlasLookup,
+  AtlasSprite,
+  IconAtlas,
+  SpriteQuery,
+} from '@terrafirmagreg-team/game/lib/dump/assets/atlas/dto';
+import {
+  asTaggedReference,
+  nbtSpecificity,
+  parseStackId,
+} from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+import type { DumpNbt, TaggedReference } from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+import { formatNbt } from '@terrafirmagreg-team/game/lib/snbt';
+
+export { atlasPagePublicUrl } from '@terrafirmagreg-team/game/lib/dump/assets/urls';
+
+function asStackKind(
+  kind: string | undefined,
+): SpriteQuery['kind'] | undefined {
+  return kind === 'item' || kind === 'block' || kind === 'fluid' ? kind : undefined;
+}
+
+function asSpriteQuery(
+  value: string | TaggedReference | SpriteQuery | null | undefined,
+  kind?: SpriteQuery['kind'],
+): SpriteQuery | null {
+  if (value == null) return null;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!trimmed) return null;
+    const parsed = parseStackId(trimmed);
+    if (!parsed.id) return null;
+    return {
+      id: parsed.id,
+      ...(kind ? { kind } : {}),
+      ...(parsed.nbt !== undefined ? { tag: parsed.nbt } : {}),
+    };
+  }
+  const tagged = asTaggedReference(value);
+  if (tagged) {
+    const stackKind = asStackKind(tagged.kind);
+    if (!stackKind) return null;
+    return {
+      kind: kind ?? stackKind,
+      id: tagged.id,
+      ...(tagged.tag !== undefined ? { tag: tagged.tag } : {}),
+    };
+  }
+  if (typeof value === 'object' && typeof value.id === 'string' && value.id) {
+    const resolvedKind = kind ?? asStackKind(value.kind);
+    return {
+      id: value.id,
+      ...(resolvedKind ? { kind: resolvedKind } : {}),
+      ...(value.tag !== undefined ? { tag: value.tag } : {}),
+    };
+  }
+  return null;
+}
+
+function spriteScore(
+  ref: TaggedReference,
+  query: SpriteQuery,
+  preferVariant: boolean,
+): number {
+  if (ref.id !== query.id) return -1;
+  if (query.kind && ref.kind !== query.kind) return -1;
+  if (query.tag === undefined) {
+    if (ref.tag === undefined) return 500;
+    return preferVariant ? 600 : -1;
+  }
+  if (ref.tag === undefined) return 100;
+  return nbtSpecificity(ref.tag, query.tag);
+}
+
+type SpriteBucket = {
+  all: AtlasSprite[];
+  untagged: AtlasSprite[];
+  tagged: AtlasSprite[];
+  byTag: Map<string, AtlasSprite[]>;
+  maxTagKeys: number;
+};
+
+const atlasIndex = new WeakMap<IconAtlas, Map<string, SpriteBucket>>();
+
+const EXACT_SAFE_MAX_KEYS = 99;
+
+function nbtTopKeys(tag: DumpNbt | undefined): number {
+  return tag !== null && typeof tag === 'object' && !Array.isArray(tag)
+    ? Object.keys(tag ?? {}).length
+    : 0;
+}
+
+function spriteBuckets(atlas: IconAtlas): Map<string, SpriteBucket> {
+  let byId = atlasIndex.get(atlas);
+  if (byId) return byId;
+  byId = new Map();
+  for (const sprite of atlas.sprites) {
+    const bucket =
+      byId.get(sprite.ref.id) ??
+      (() => {
+        const created: SpriteBucket = {
+          all: [],
+          untagged: [],
+          tagged: [],
+          byTag: new Map(),
+          maxTagKeys: 0,
+        };
+        byId.set(sprite.ref.id, created);
+        return created;
+      })();
+    bucket.all.push(sprite);
+    if (sprite.ref.tag === undefined) {
+      bucket.untagged.push(sprite);
+      continue;
+    }
+    bucket.tagged.push(sprite);
+    const keyCount = nbtTopKeys(sprite.ref.tag);
+    if (keyCount > bucket.maxTagKeys) bucket.maxTagKeys = keyCount;
+    const key = formatNbt(sprite.ref.tag);
+    if (key !== undefined) {
+      const list = bucket.byTag.get(key);
+      if (list) list.push(sprite);
+      else bucket.byTag.set(key, [sprite]);
+    }
+  }
+  atlasIndex.set(atlas, byId);
+  return byId;
+}
+
+function spriteHit(
+  atlas: IconAtlas,
+  sprite: AtlasSprite,
+): AtlasLookup | null {
+  const page = atlas.pages[sprite.page];
+  return page ? { atlas, sprite, page, spriteId: sprite.ref.id } : null;
+}
+
+function lookupSprite(
+  atlas: IconAtlas | null | undefined,
+  query?: string | TaggedReference | SpriteQuery | null,
+  kind?: SpriteQuery['kind'],
+  preferVariant = false,
+): AtlasLookup | null {
+  if (!atlas || query == null) return null;
+  const resolved = asSpriteQuery(query, kind);
+  if (!resolved) return null;
+  const bucket = spriteBuckets(atlas).get(resolved.id);
+  if (!bucket) return null;
+  if (resolved.tag === undefined) {
+    const first = preferVariant ? bucket.tagged : bucket.untagged;
+    const second = preferVariant ? bucket.untagged : bucket.tagged;
+    for (const list of [first, second]) {
+      for (const sprite of list) {
+        if (resolved.kind && sprite.ref.kind !== resolved.kind) continue;
+        const hit = spriteHit(atlas, sprite);
+        if (hit) return hit;
+      }
+    }
+    return null;
+  }
+  if (bucket.maxTagKeys <= EXACT_SAFE_MAX_KEYS) {
+    const exacts = bucket.byTag.get(formatNbt(resolved.tag) ?? '');
+    if (exacts) {
+      for (const sprite of exacts) {
+        if (resolved.kind && sprite.ref.kind !== resolved.kind) continue;
+        const hit = spriteHit(atlas, sprite);
+        if (hit) return hit;
+      }
+    }
+  }
+  let best: AtlasLookup | null = null;
+  let bestScore = -1;
+  for (const sprite of bucket.all) {
+    const score = spriteScore(sprite.ref, resolved, preferVariant);
+    if (score <= bestScore) continue;
+    const hit = spriteHit(atlas, sprite);
+    if (!hit) continue;
+    best = hit;
+    bestScore = score;
+  }
+  return best;
+}
+
+export function lookupSpriteInBundle(
+  bundle: { items: IconAtlas | null; blocks: IconAtlas | null } | null | undefined,
+  query?: string | TaggedReference | SpriteQuery | null,
+  kind?: SpriteQuery['kind'],
+  preferVariant = false,
+): AtlasLookup | null {
+  if (!bundle) return null;
+  const resolved = asSpriteQuery(query, kind);
+  if (!resolved) return null;
+  if (resolved.kind === 'block') {
+    return (
+      lookupSprite(bundle.blocks, resolved, undefined, preferVariant) ??
+      lookupSprite(bundle.items, resolved, undefined, preferVariant)
+    );
+  }
+  if (resolved.kind === 'item' || resolved.kind === 'fluid') {
+    return lookupSprite(bundle.items, resolved, undefined, preferVariant);
+  }
+  return (
+    lookupSprite(bundle.items, resolved, undefined, preferVariant) ??
+    lookupSprite(bundle.blocks, resolved, undefined, preferVariant)
+  );
+}