bc-deeplib 1.0.5 → 1.1.0

package/CREDITS.md

@@ -0,0 +1,13 @@
+## Assets
+
+- Git Logo by [Jason Long](https://bsky.app/profile/jasonlong.me) is licensed under the [Creative Commons Attribution 3.0 Unported License](https://creativecommons.org/licenses/by/3.0/).
+  - Changes: Added padding
+  - Source: https://git-scm.com/images/logos/downloads/Git-Icon-White.svg
+
+- [Transfer Vertical, Notebook, Trash Bin Trash, Bug, Login 2, Alt Arrow Right, Alt Arrow Left, File Download, File Send] by [Solar Icons](https://www.figma.com/community/file/1166831539721848736?ref=svgrepo.com), in [CC Attribution License](https://creativecommons.org/licenses/by/4.0/)
+  - Changes: Color adjusted
+  - Source: https://www.svgrepo.com/collection/solar-outline-icons/
+
+- [Clipboard Add] by [Solar Icons](https://www.figma.com/community/file/1166831539721848736?ref=svgrepo.com), in [CC Attribution License](https://creativecommons.org/licenses/by/4.0/)
+  - Changes: Color adjusted, plus symbol replaced with an arrow
+  - Source: https://www.svgrepo.com/collection/solar-outline-icons/

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 dDeepLb
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 dDeepLb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,2 +1,2 @@
-## Deep Lib
-Package for easier development of BC mods.
+## Deep Lib
+Package for easier development of BC mods.

package/dist/3rd_party_types/bcmodsdk.d.ts

@@ -0,0 +1,184 @@
+/**
+ * A type signifying any unknown function.
+ * @public
+ */
+declare type AnyFunction = (...args: any) => any;
+
+/** @public */
+declare const bcModSdk: ModSDKGlobalAPI;
+
+/**
+ * @public
+ * A helper to resolve dotted property path to the target type
+ * @example
+ * typeof window["a"]["b"]["c"] === GetDotedPathType\<typeof window, "a.b.c"\>
+ */
+declare type GetDotedPathType<Base, DotedKey extends string> = DotedKey extends `${infer Key1}.${infer Key2}`
+  ? GetDotedPathType<GetDotedPathType<Base, Key1>, Key2>
+  : DotedKey extends keyof Base
+    ? Base[DotedKey]
+    : never;
+
+/**
+ * The global API of the SDK
+ *
+ * Accessible using the exported value or as `window.bcModSdk`
+ * @public
+ */
+declare interface ModSDKGlobalAPI {
+  /** The version of the SDK itself. Attempting to load two different SDK versions will warn, but work as long as `apiVersion` is same. */
+  readonly version: string;
+  /** The API version of the SDK itself. Attempting to load two different SDK versions will fail. */
+  readonly apiVersion: number;
+  /**
+   * Register a mod, receiving access to the mod API
+   * @param info - Info about the mod, necessary to register the mod
+   * @param options - [OPTIONAL] Options the mod can specify for ModSDK
+   * @returns The API usable by mod. @see ModSDKModAPI
+   * @see ModSDKModInfo
+   */
+  registerMod(info: ModSDKModInfo, options?: ModSDKModOptions): ModSDKModAPI;
+  /** Get info about all registered mods */
+  getModsInfo(): ModSDKModInfo[];
+  /** Get info about all modified functions */
+  getPatchingInfo(): Map<string, PatchedFunctionInfo>;
+  /** Internal API, please **DO NOT USE** */
+  readonly errorReporterHooks: {
+    apiEndpointEnter: ((fn: string, mod: string) => () => void) | null;
+    hookEnter: ((fn: string, mod: string) => () => void) | null;
+    hookChainExit: ((fn: string, patchMods: ReadonlySet<string>) => () => void) | null;
+  };
+}
+
+/** @public */
+declare interface ModSDKModAPI {
+  /** Unload this mod, removing any hooks or patches by it. To continue using SDK another call to `registerMod` is required */
+  unload(): void;
+  /**
+   * Hook a BC function
+   * @template TFunctionName - The name of the hooked function, _e.g._ `"Player.CanChange"`
+   * @param functionName - Name of function to hook. Can contain dots to change methods in objects (e.g. `Player.CanChange`)
+   * @param priority - Number used to determinate order hooks will be called in. Higher number is called first
+   * @param hook - The hook itself to use, @see PatchHook
+   * @returns Function that can be called to remove this hook
+   */
+  hookFunction<TFunctionName extends string>(
+    functionName: TFunctionName,
+    priority: number,
+    hook: PatchHook<GetDotedPathType<typeof globalThis, TFunctionName>>
+  ): () => void;
+  /**
+   * Call original function, bypassing any hooks and ignoring any patches applied by ALL mods.
+   * @template TFunctionName - The name of the called function, _e.g._ `"Player.CanChange"`
+   * @param functionName - Name of function to call. Can contain dots to change methods in objects (e.g. `Player.CanChange`)
+   * @param args - Arguments to use for the call
+   * @param context - `this` context to use. Defaults to `window`. If calling method of object, then set this to the object itself (e.g. `functionName` = `Player.CanChange` then `context` = `Player`)
+   */
+  callOriginal<TFunctionName extends string>(
+    functionName: TFunctionName,
+    args: [...Parameters<GetDotedPathType<typeof globalThis, TFunctionName>>],
+    context?: any
+  ): ReturnType<GetDotedPathType<typeof globalThis, TFunctionName>>;
+  /**
+   * Patch a BC function
+   *
+   * **This method is DANGEROUS** to use and has high potential to conflict with other mods.
+   *
+   * Only use it if what you are trying to accomplish can't be done easily with `hookFunction`.
+   *
+   * This function tranforms BC function to string, replaces patches as pure text and then `eval`uates it.
+   * If you don't know what this means, please avoid this function.
+   * @template TFunctionName - The name of the patched function, _e.g._ `"Player.CanChange"`
+   * @param functionName - Name of function to patch. Can contain dots to change methods in objects (e.g. `Player.CanChange`)
+   * @param patches - Object in key: value format, where keys are chunks to replace and values are result.
+   *
+   * Patches from multiple calls are merged; where key matches the older one is replaced.
+   * Specifying value of `null` removes patch with this key.
+   */
+  patchFunction<TFunctionName extends string>(
+    functionName: TFunctionName,
+    patches: GetDotedPathType<typeof globalThis, TFunctionName> extends AnyFunction ? Record<string, string | null> : never
+  ): void;
+  /**
+   * Remove all patches by `patchFunction` from specified function.
+   * @param functionName - Name of function to patch. Can contain dots to change methods in objects (e.g. `Player.CanChange`)
+   */
+  removePatches(functionName: string): void;
+  /**
+   * Get hash of original function in CRC32.
+   *
+   * The hash is computed from source obtained using `toString` with line endings normalized to LF
+   * @param functionName - Name of function. Can contain dots to change methods in objects (e.g. `Player.CanChange`)
+   */
+  getOriginalHash(functionName: string): string;
+}
+
+/**
+ * Info about a mod registered within the Mod SDK
+ * @public
+ */
+declare interface ModSDKModInfo {
+  /** Short name or abbreviation of the mod */
+  name: string;
+  /** Full name of the mod */
+  fullName: string;
+  /** Version or other metadata for the mod, visible by other mods */
+  version: string;
+  /** Link to public repository with source code for this mod */
+  repository?: string;
+}
+
+/**
+ * Additional options mods can optionally give when registering
+ * @public
+ */
+declare interface ModSDKModOptions {
+  /**
+   * [OPTIONAL]
+   *
+   * If `true` subsequent calls to `registerMod` will unload old one, replacing it.
+   *
+   * If `false` any attempt to register a new mod with same name will fail.
+   * @default false
+   */
+  allowReplace?: boolean;
+}
+
+/**
+ * Info about a function modified using the API
+ * @public
+ */
+declare interface PatchedFunctionInfo {
+  name: string;
+  /** The original function */
+  original?: (...args: any[]) => any;
+  /** CRC32 has of the original function */
+  originalHash: string;
+  /** SDK-generated entrypoint that the global function was replaced with */
+  sdkEntrypoint?: (...args: any[]) => any;
+  /**
+   * Entrypoint that SDK collected at the time of calling of the `getPatchingInfo` method.
+   *
+   * If the function wasn't overwritten, it should equal `sdkEntrypoint`
+   */
+  currentEntrypoint?: (...args: any[]) => any;
+  /** List of names of mods that hooked this function */
+  hookedByMods: string[];
+  /** List of names of mods that patched this function */
+  patchedByMods: string[];
+}
+
+/**
+ * This is how hook from mod looks like.
+ *
+ * As first argument it receives all arguments the original function received.
+ *
+ * As second argument special `next` function that should be used to call original function (or next function in the hook chain).
+ *
+ * The return value is then used as return value instead of original one.
+ * @public
+ */
+declare type PatchHook<TFunction extends AnyFunction = AnyFunction> = (
+  args: [...Parameters<TFunction>],
+  next: (args: [...Parameters<TFunction>]) => ReturnType<TFunction>
+) => ReturnType<TFunction>;

package/dist/3rd_party_types/declarations.d.ts

@@ -0,0 +1,4 @@
+declare const PUBLIC_URL: string;
+declare const MOD_VERSION: string;
+declare const VERSION_HASH: string;
+declare const IS_DEVEL: boolean;