@genart-api/core

import type { Param, ParamSpecs } from "./params.js"; import type { PRNG } from "./random.js"; import type { ScreenConfig } from "./screen.js"; import type { Traits } from "./traits.js"; /** * Platform defined presentation mode for the artwork: * * - `play`: default mode * - `preview`: capturing, thumbnail, etc. * - `edit`: platform has param editor active */ export type RunMode = "play" | "preview" | "edit"; /** * A plugin component responsible to implement and/or negotiate **any** platform * specific behavior of the overall {@link GenArtAPI} functionality. To * repurpose an artwork for a different platform, artist should only require to * switch out a single `<script>` tag in the HTML wrapper of their piece, but * otherwise require **zero** code changes. */ export interface PlatformAdapter { readonly mode: RunMode; readonly screen: ScreenConfig; readonly prng: PRNG; readonly seed: string; /** * Human-readable but unique identifier for this platform adapter * implementation. * * @remarks * This ID should be derrived from the target art platform's name, domain * name or package name, and can also include version info. * * External tooling (e.g. parameter editors) can utilize this information to * inform/warn about compatibility. Also see {@link InfoMessage} for related * use cases. */ readonly id: string; /** * Platform supplied ID of the person/agent collecting/creating/minting the * current artwork. Undefined if the platform doesn't support this concept. * * @remarks * This API is not intended to be tied up with crypto/NFT-based concepts, * even though currently it's likely only NFT platforms will or can provide * this kind of information. * * Currently, there're no guarantees or constraints for this value. Even the * concrete meaning & stability of a "collector" value here is also left * wide open on purpose. For a custom digital art online store this could be * the name of the collector/customer, but on supporting NFT platforms it * would likely be the address of the person/agent who minted the artwork. * * Also see {@link PlatformAdapter.iteration}. */ readonly collector?: string; /** * Platform supplied iteration number of the artwork's edition. * Undefined if platform doesn't support this concept. * * @remarks * Also see {@link PlatformAdapter.collector}. */ readonly iteration?: number; /** * Called by {@link GenArtAPI.setParams} to receive parameter specs provided * by the artwork and to allow the adapter to inject additional platform * specific parameters into the given {@link ParamSpecs} object. * * @remarks * **No platform-specific param initialization should happen at this * stage.** The param specs passed to this function might be still not fully * initialized (i.e. might still have missing default values). The same goes * for any params injected here. Use {@link PlatformAdapter.initParams} for * actual platform specific initialization (which will be called * automatically if present, see lifecycle diagram). * * **If additional parameters are injected, the adapter MUST ensure their * naming doesn't override existing params, i.e. these param names should be * prefixed with a platform specific prefix (e.g. `foo:` or `__`)** * * @param params */ augmentParams?(params: ParamSpecs): ParamSpecs; /** * Called by {@link GenArtAPI.setParams} to receive fully initialized * parameter specs provided by the artwork (and possibly augmented by * {@link PlatformAdapter.augmentParams}. This function allows the adapter * to prepare itself for param initialization (e.g. initiating a network * request for loading parameter overrides). This function is async and MUST * throw an error if pre-initialization failed on the adapter's side. * * @remarks * The actual value parsing of individual parameter customization only * happens later via {@link PlatformAdapter.updateParam} (which is also * indirectly called by {@link GenArtAPI.setParams} after this function * returns). * * @param params */ initParams?(params: ParamSpecs): Promise<void>; /** * Called by {@link GenArtAPI.updateParams} (and indirectly by * {@link GenArtAPI.setParams}) to possibly augment/update a single param * spec with any customizations sourced via platform-specific means (e.g. * from URL query-string params). * * @remarks * The function can return one of the following: * * 1. If the function returns `void`, no customizations found/performed and * no notifications will be triggered. * 3. If the function returns `{ update: { key1: any, key2: any, ...} }`, * the given keys in the param spec will be modified/customized with * their new values via calling {@link GenArtAPI.setParamValue} for each * key-value pair. The keys to be updated MUST correspond to nested param * specs defined by the main param type's {@link ParamImpl.params}, * otherwise an error will be thrown (see [Composite * parameters](https://github.com/thi-ng/genart-api/blob/main/README.md#composite-parameters) * for reference). * 3. If the function returns `{ value: any }` and if that `value` is * non-nullish, the param spec will be updated via * {@link GenArtAPI.setParamValue}. * * If this function returned a `value` and/or `update`, and if the retured * value(s) passed param type-specific validation (see * {@link ParamImpl.validate}), then by default * {@link GenArtAPI.setParamValue} emits a {@link ParamChangeMessage} message * with the updated param spec. * * @param id * @param spec */ updateParam(id: string, spec: Readonly<Param<any>>): Promise<{ value?: any; update?: Record<string, any>; } | void>; /** * See {@link GenArtAPI.setTraits}. * * @param traits */ setTraits?(traits: Traits): void; /** * Platform-specific handler to deal with capturing a thumbnail/preview of * the art piece. (e.g. by sending a message to the parent window). See * {@link GenArtAPI.capture}. * * @param el */ capture(el?: HTMLCanvasElement | SVGElement): void; }