Merge pull request 'Update to Profectus 0.7' (#13) from feat/boards i…

…nto main Reviewed-on: https://code.incremental.social/profectus/profectus-docs/pulls/13
profectus-engine · Dec 31, 2024 · bac570e · bac570e
2 parents 44a689a + 45e48d2
commit bac570e
Show file tree

Hide file tree

Showing 102 changed files with 4,337 additions and 3,805 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,4 +4,4 @@ docs/.vitepress/dist
 docs/.vitepress/cache
 docs/api
 components
-typedoc-theme
+typedoc-sidebar.json
diff --git a/docgen.config.js b/docgen.config.js
@@ -9,7 +9,7 @@ module.exports = {
     jsx: true // tell vue-docgen-api that your components are using JSX to avoid conflicts with TypeScript <type> syntax
   },
   getDestFile: (file, config) =>
-    path.join(config.outDir, file).replace(/\.vue$/, 'Component.md'), // specify the name of the output md file
+    path.join(config.outDir, file).replace(/\.vue$/, '.md'), // specify the name of the output md file
   templates: {
     // global component template wrapping all others see #templates
     component,
@@ -30,59 +30,83 @@ function component(renderedUsage, // props, events, methods and slots documentat
   // attached to the component documented. It includes documentation of subcomponents
   { isSubComponent, hasSubComponents }) {
   const { displayName, description, docsBlocks } = doc
-  return `
-  ### ${displayName} Component
+  return `# Component: ${displayName}
 
-  ${description ? '> ' + description : ''}
+${description}
 
-  ${renderedUsage.props}
-  ${renderedUsage.methods}
-  ${renderedUsage.events}
-  ${renderedUsage.slots}
-  ${docsBlocks?.length ? '---\n' + docsBlocks.join('\n---\n') : ''}
-  `
+${renderedUsage.props}
+${renderedUsage.methods}
+${renderedUsage.events}
+${renderedUsage.slots}
+${docsBlocks?.length ? '---\n' + docsBlocks.join('\n---\n') : ''}
+
+## Defined in
+
+[profectus/src/${fileName}](https://code.incremental.social/profectus/Profectus/src/branch/main/src/${fileName})
+`.replaceAll('`Resource`', '[`Resource`](/api/features/resources/resource/interfaces/Resource)')
+.replaceAll('`MaybeGetter`', '[`MaybeGetter`](/api/util/computed/type-aliases/MaybeGetter)')
+.replaceAll('`Error`', '[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)')
+.replaceAll('`MouseEvent`', '[`MouseEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent)')
+.replaceAll('`TouchEvent`', '[`TouchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent)')
+.replaceAll('`Hotkey`', '[`Hotkey`](/api/features/hotkey/interfaces/Hotkey)')
+.replaceAll('`Requirements`', '[`Requirements`](/api/game/requirements/interfaces/Requirement)')
+.replaceAll('`Renderable`', '[`Renderable`](/api/util/vue/type-aliases/Renderable)')
+.replaceAll('`Direction`', '[`Direction`](/api/util/common/enumerations/Direction)')
+.replaceAll('`DecimalSource`', '[`DecimalSource`](/api/util/bignum/type-aliases/DecimalSource)')
+.replaceAll('`Visibility`', '[`Visibility`](/api/features/feature/enumerations/Visibility)')
+.replaceAll('`Link`', '[`Link`](/api/features/links/links/interfaces/Link)')
+.replaceAll('`FeatureNode`', '[`FeatureNode`](/api/game/layers/interfaces/FeatureNode)')
+.replaceAll('`DOMRect`', '[`DOMRect`](https://developer.mozilla.org/en-US/docs/Web/API/DOMRect)')
+.replaceAll('`Tab`', '[`Tab`](/api/features/tabs/tab/interfaces/Tab)')
+.replaceAll('`TabButton`', '[`TabButton`](/api/features/tabs/tabFamily/interfaces/TabButton)')
+.replaceAll('`TreeNode`', '[`TreeNode`](/api/features/trees/tree/interfaces/TreeNode)')
+.replaceAll('`TreeBranch`', '[`TreeBranch`](/api/features/trees/tree/interfaces/TreeBranch)')
+.replaceAll('`Wrapper`', '[`Wrapper`](/api/util/vue/type-aliases/Wrapper)')
+.replaceAll('`LoadablePlayerData`', '[`LoadablePlayerData`](/api/util/save/type-aliases/LoadablePlayerData)')
+// ^ Manually created for the types I am currently noticing show up in components
+}
+
+function displayType(type) {
+    let n = type?.name ?? type?.names?.[0] ?? '';
+    if (n === "union") n = type?.elements.map(displayType).join(' | ')
+    else if (n === "Array") n = (type?.elements.length > 1 ? "(" : "") + type?.elements.map(el => el.name).join(' | ') + (type?.elements.length > 1 ? ")" : "") + "[]"
+    else if (n && type?.elements?.length > 0) n = `\`${n}\`<${type.elements.map(displayType).join(", ")}>`
+    else n = `\`${n}\``
+    return n;
 }
 
-const eventCols = ["Name", "Description", "Properties"];
+const eventCols = ["Name", "Description", "Parameter", "Return"];
 const eventShouldDisplayCol = {
   [eventCols[0]]: event => event.name,
-  [eventCols[1]]: event => event.description,
-  [eventCols[2]]: event => event.properties?.length
+  [eventCols[1]]: event => true,
+  [eventCols[2]]: event => event.type,
+  [eventCols[3]]: event => true
 }
 const eventGetDisplay = {
-  [eventCols[0]]: event => `<code>${clean(event.name)}</code>`,
-  [eventCols[1]]: event => clean(event.description || ""),
-  [eventCols[2]]: event => {
-    if (!event.properties) return "";
-    return event.properties.map(property => {
-      const { name, description, type } = property
-      if (!type) {
-        return ''
-      }
-      return `**${name}** <code>${clean(type.names.length ? type.names.join(', ') : '')}</code> - ${description}`
-    }).join('<br/>')
-  }
+  [eventCols[0]]: event => `${clean(event.name)}()`,
+  [eventCols[1]]: event => `> **${clean(event.name)}**: (${event.type ? `\`parameter\`` : ''}) => \`void\`\n\n${clean(event.description || "")}`,
+  [eventCols[2]]: event => event.type ? `#### Parameters\n\n\n##### parameter\n\n\n${displayType(event.type)}` : '',
+  [eventCols[3]]: event => `#### Returns\n\n\n\`void\``
 }
 
-const propCols = ["Name", "Type", "Description", "Values", "Default"];
+const propCols = ["Name", "Type", "Description", "Values"/*, "Default"*/];
 const propShouldDisplayCol = {
   [propCols[0]]: pr => pr.name,
   [propCols[1]]: pr => pr.type?.name,
   [propCols[2]]: pr => pr.description || pr.tags,
   [propCols[3]]: pr => pr.values,
-  [propCols[4]]: pr => pr.defaultValue
+  // [propCols[4]]: pr => pr.defaultValue
 }
 const propGetDisplay = {
-  [propCols[0]]: pr => `<code>${clean(pr.name)}</code>` + (pr.required ? "*" : ""),
+  [propCols[0]]: pr => clean(pr.name) + (pr.required ? "" : "?"),
   [propCols[1]]: pr => {
-    let n = pr.type?.name ?? ''
-    if (n === "union") n = pr.type?.elements.map(el => el.name).join(' | ')
-    if (n === "Array") n = (pr.type?.elements.length > 1 ? "(" : "") + pr.type?.elements.map(el => el.name).join(' | ') + (pr.type?.elements.length > 1 ? ")" : "") + "[]"
-    return n ? '<code>' + clean(n) + '</code>' : ''
+    if (!pr.type) return '';
+    let n = displayType(pr.type);
+    return `> ${clean(n)}`;
   },
   [propCols[2]]: pr => clean((pr.description ?? '') + renderTags(pr.tags)),
   [propCols[3]]: pr => clean(pr.values?.map(pv => `\`${pv}\``).join(', ') ?? '-'),
-  [propCols[4]]: pr => clean(pr.defaultValue?.value ?? '')
+  // [propCols[4]]: pr => clean(pr.defaultValue?.value ?? '')
 }
 
 const slotCols = ["Name", "Description", "Bindings"];
@@ -92,38 +116,30 @@ const slotShouldDisplayCol = {
   [slotCols[2]]: slot => slot.bindings?.length
 }
 const slotGetDisplay = {
-  [slotCols[0]]: slot => `<code>${clean(slot.name)}</code>`,
+  [slotCols[0]]: slot => clean(slot.name),
   [slotCols[1]]: slot => clean(slot.description || ""),
   [slotCols[2]]: slot => {
-    if (!slot.bindings) return "";
-    return slot.bindings.map(binding => {
-      const { name, description, type } = binding
-      if (!type) {
-        return ''
-      }
-      return `**${name}** <code>${
-        type.name === 'union' && type.elements
-          ? type.elements.map(({ name: insideName }) => insideName).join(', ')
-          : type.name
-      }</code> - ${description}`
-    }).join('<br/>')
+    if (!slot.bindings) return '';
+    let output = `#### Bindings\n`;
+    slot.bindings.forEach(({ name, description, type }) => {
+      output += `\n##### ${name}\n\n\n${displayType(type)}\n\n\n${description}`;
+    });
+    return output;
   }
 }
 
 function displayUsedCols(title, cols, shouldDisplayCol, getDisplay, rows, opt) {
   cols = cols.filter(col => rows.some(shouldDisplayCol[col]));
   if (!cols) return "";
 
-  let output = `\n${opt.isSubComponent || opt.hasSubComponents ? '#' : ''}#### ${title}\n|`;
-  cols.forEach(col => (output += ` ${col} |`));
-  output += `\n|`;
-  cols.forEach(col => (output += ' :-- |'));
-  output += '\n';
-
-  rows.forEach(row => {
-    output += "|";
-    cols.forEach(col => (output += ` ${getDisplay[col](row)} |`));
-    output += "\n";
+  let output = `\n${opt.isSubComponent || opt.hasSubComponents ? '#' : ''}## ${title}\n`;
+  rows.forEach((row, i) => {
+    const [name, ...other] = cols;
+    if (i > 0) output += "\n***\n";
+    output += `\n${opt.isSubComponent || opt.hasSubComponents ? '#' : ''}### ${getDisplay[name](row)}\n`;
+    other.forEach(col => {
+      output += `\n ${getDisplay[col](row)}\n`;
+    });
   });
 
   return output;

diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -11,7 +11,6 @@ module.exports = {
     ['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/favicon-32x32.png' }],
     ['link', { rel: 'icon', type: 'image/png', sizes: '16x16', href: '/favicon-16x16.png' }],
     ['link', { rel: 'manifest', href: '/site.webmanifest' }],
-    ['script', { defer: true, 'data-domain': 'moddingtree.com', src: 'https://plausible.io/js/plausible.js' }],
     ['meta', { name: 'og:description', content: 'A game engine that grows with you' }],
     ['meta', { name: 'og:image', content: '/Logo.png' }]
   ],
@@ -21,12 +20,12 @@ module.exports = {
   themeConfig: {
     logo: "/favicon.svg",
     editLink: {
-      pattern: "https://code.incremental.social/profectus/profectus-docs/edit/main/docs/:path",
+      pattern: "https://code.incremental.social/profectus/profectus-docs/_edit/main/docs/:path",
       editLinkText: "Edit this page on Incremental Social"
     },
     nav: [
       { text: "Guide", link: "/guide/", activeMatch: "^/guide/" },
-      { text: "API", link: "/api/overview", activeMatch: "^/api/" },
+      { text: "API", link: "/api", activeMatch: "^/api/" },
       { text: "Forums", link: "https://forums.moddingtree.com" }
     ],
     socialLinks: [
@@ -64,7 +63,6 @@ module.exports = {
           items: [
             { text: "Layers", link: "/guide/important-concepts/layers" },
             { text: "Features", link: "/guide/important-concepts/features" },
-            { text: "Coercable Components", link: "/guide/important-concepts/coercable" },
             { text: "Reactivity", link: "/guide/important-concepts/reactivity" },
             { text: "Persistence", link: "/guide/important-concepts/persistence" },
             { text: "Requirements", link: "/guide/important-concepts/requirements" },
@@ -77,91 +75,41 @@ module.exports = {
           items: [
             { text: "Prestige Mechanic", link: "/guide/recipes/prestige" },
             { text: "Display Save Progress", link: "/guide/recipes/save-progress" },
-            { text: "Display Particle Effect", link: "/guide/recipes/particles" }
+            { text: "Display Particle Effect", link: "/guide/recipes/particles" },
+            { text: "Resources on Forums", link: "https://forums.moddingtree.com/tags/c/modding-help/resources/17/profectus" }
           ]
         },
         {
           text: "Advanced Concepts",
           collapsed: false,
           items: [
+            { text: "Boards", link: "/guide/advanced-concepts/boards" },
             { text: "Creating Features", link: "/guide/advanced-concepts/creating-features" },
             { text: "Dynamic Layers", link: "/guide/advanced-concepts/dynamic-layers" },
+            { text: "Mixins and Wrappers", link: "/guide/advanced-concepts/mixins" },
             { text: "Nodes", link: "/guide/advanced-concepts/nodes" }
           ]
         },
         {
           text: "Migrations",
           collapsed: true,
           items: [
-            { text: "0.5.X to 0.6.0", link: "/guide/migrations/0-6" }
+            { text: "0.5.X to 0.6.0", link: "/guide/migrations/0-6" },
+            { text: "0.6.X to 0.7.0", link: "/guide/migrations/0-7" }
           ]
         }
       ],
     "/api/": generateAPISidebar()
     }
+  },
+  markdown: {
+    theme: {
+      light: "material-theme-palenight",
+      dark: "material-theme-palenight"
+    }
   }
 }
 
 function generateAPISidebar() {
-  const sidebar = [];
-
-  const modules = fs.readdirSync("./docs/api/modules");
-  modules.forEach(file => {
-    const moduleSidebar = { text: camelToTitle(file), items: [], collapsed: file === "lib" };
-    sidebar.push(moduleSidebar)
-    walk(path.join("./docs/api/modules", file), moduleSidebar.items);
-  });
-
-  const componentFolders = [];
-  walk("./docs/api/components", componentFolders);
-  sidebar.unshift({
-    text: "Components",
-    collapsed: true,
-    items: componentFolders
-  });
-
-  sort(sidebar);
-
-  return sidebar;
-}
-
-function sort(sidebar) {
-  sidebar.filter(sidebar => !!sidebar.items).forEach(item => sort(item.items));
-  sidebar.sort((a, b) => {
-    if (a.items && !b.items) {
-      return -1;
-    } else if (!a.items && b.items) {
-      return 1;
-    } else if (a.text > b.text) {
-      return 1;
-    } else if (a.text < b.text) {
-      return -1;
-    } else {
-      return 0;
-    }
-  });
-}
-
-function walk(dir, sidebar) {
-  const files = fs.readdirSync(dir);
-  files.forEach(file => {
-    const resolvedFile = path.join(dir, file);
-    const stat = fs.statSync(resolvedFile);
-    if (stat.isDirectory()) {
-      const subSidebar = { text: camelToTitle(file), items: [], collapsed: true };
-      sidebar.push(subSidebar);
-      walk(resolvedFile, subSidebar.items);
-    } else if (!file.includes("Component") || dir.includes("components")) {
-      sidebar.push({ text: camelToTitle(file.substr(0, file.length - 3)), link: "/" + resolvedFile.substr(5, resolvedFile.length - 8).replace(/\\/g, "/") + ".html" });
-    }
-  });
-}
-
-function camelToTitle(camel) {
-    if (camel === "break_eternity") {
-      return "Break Eternity";
-    }
-    let title = camel.replace(/([A-Z])/g, " $1");
-    title = title.charAt(0).toUpperCase() + title.slice(1);
-    return title;
+  return JSON.parse(fs.readFileSync("./typedoc-sidebar.json").toString().replaceAll("..\\\\docs\\\\", ""));
 }
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -56,3 +56,11 @@ body {
 .VPSocialLink > svg {
     width: 30px !important;
 }
+
+.VPBadge {
+    color: var(--vp-badge-info-text) !important;
+}
+
+.title {
+    border-bottom: none !important;
+}
diff --git a/docs/.vitepress/theme/vars.css b/docs/.vitepress/theme/vars.css
@@ -21,6 +21,7 @@
   --vp-c-brand-3: #5E81AC;
   --vp-c-brand-light: #81A1C1;
   --vp-c-brand-dark: #81A1C1;
+  --vp-c-gutter: #3B4252;
   --vp-button-brand-border: #81A1C1;
   --vp-button-brand-text: #ECEFF4;
   --vp-button-brand-hover-text: #ECEFF4;