A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { Color, Entity } from '../../types';
import type { World } from '../../ecs/world';
import {
UIVisual,
UIVisualType,
FillMethod,
FillOrigin,
type UIVisualData,
} from '../core/ui-visual';
import { spawnUIEntity, FILL_AXIS, type UINodeInit, type UIVisualInit, type LinearFillDirection } from '../core/compose';
import { themeColors } from '../theme/tokens';
import { markThemed } from '../theme/theme-style';
export interface ProgressOptions {
world: World;
parent?: Entity;
node?: UINodeInit;
/** Background (track) renderer. */
background?: UIVisualInit;
/** Fill renderer config (the filled bar). */
fill?: { color?: Color; sprite?: number };
/** Direction the fill grows (linear bars). Default: 'right'. */
direction?: LinearFillDirection;
/** Radial gauge: a clockwise wedge from 12 o'clock; `direction` is ignored. */
radial?: boolean;
/** Initial progress 0..1. Default 0. */
value?: number;
}
export interface ProgressHandle {
readonly entity: Entity;
readonly fillEntity: Entity;
getValue(): number;
setValue(v: number): void;
dispose(): void;
}
/**
* Linear progress bar. Two entities: a track (background) and a fill child
* that stretches over the track as a {@link UIVisualType.Filled} visual —
* `setValue` writes `fillAmount`, so the bar is a render-time crop with no
* per-frame layout pass, and a sprite fill reveals (not stretches). Direction
* selects the fill axis/origin.
*/
export function createProgress(opts: ProgressOptions): ProgressHandle {
const { world } = opts;
const direction = opts.direction ?? 'right';
let value = clamp01(opts.value ?? 0);
const c = themeColors();
const [fillMethod, fillOrigin] = opts.radial
? ([FillMethod.Radial360, FillOrigin.Top] as const)
: FILL_AXIS[direction];
const track = spawnUIEntity({
world,
parent: opts.parent,
node: opts.node ?? { fill: true },
visual: opts.background ?? { color: c.track },
});
if (!opts.background) markThemed(world, track, { visual: 'track' });
const fill = spawnUIEntity({
world,
parent: track,
node: { fill: true },
visual: {
visualType: UIVisualType.Filled,
color: opts.fill?.color ?? c.primary,
texture: opts.fill?.sprite ?? 0,
fillMethod,
fillOrigin,
fillAmount: value,
},
});
if (opts.fill?.color === undefined) markThemed(world, fill, { visual: 'primary' });
function setValue(v: number): void {
const next = clamp01(v);
if (next === value) return;
value = next;
const vis = world.get(fill, UIVisual) as UIVisualData;
vis.fillAmount = value;
world.insert(fill, UIVisual, vis);
}
return {
entity: track,
fillEntity: fill,
getValue: () => value,
setValue,
dispose: () => {
if (world.valid(track)) world.despawn(track);
},
};
}
function clamp01(v: number): number {
return v < 0 ? 0 : v > 1 ? 1 : v;
}