Nexo Maker

https://nexo-maker.gitbook.io/nexo-maker-docs
Admin
Nexo Maker is an all-in-one content creation platform for building powerful Minecraft content packs...
Tokens:40,624
Snippets:277
Trust Score:10
Update:11 months ago
Show doc for...
Tokens:
Raw
### Nexo Maker Asset References Example (JavaScript)

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/plugin-expansion/getting-started

Shows examples of asset references for textures and models within the Nexo Maker data model. These are provided as arrays of relative file paths, crucial for loading visual assets associated with an item.

```javascript
item.textures    // string[]: Texture file paths (e.g., ["item/magic_sword.png"])
item.models      // string[]: Model file paths (e.g., ["item/magic_sword.json"])
```

--------------------------------

### Register Export Format API Configuration (JavaScript)

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/plugin-expansion/getting-started

An example demonstrating the full configuration object for registering an export format via the Nexo Maker API. It includes optional parameters like 'files' for file structure and 'hooks' for lifecycle management.

```javascript
api.nexomaker.registerExportFormat({
  id: 'my_format',
  name: 'My Custom Format',
  transform: (item) => ({ /* transformed data */ }),
  files: { /* file configuration */ },
  hooks: { /* lifecycle hooks */ },
});
```

--------------------------------

### Nexo Maker Module Data Example (JavaScript)

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/plugin-expansion/getting-started

Provides an example of how module data is exposed in Nexo Maker. Module data is a flat object containing all registered module values for a specific item, allowing access to custom properties defined by expansions.

```javascript
{
  expansion_magic_power: 150,
  baseMaterial: "DIAMOND_SWORD",
  durability: 1000,
  // Additional module data as defined by active expansions
}
```

--------------------------------

### Register Export Format API

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/plugin-expansion/getting-started

Demonstrates how to register a custom export format using the `registerExportFormat` method.

```APIDOC
## POST /api/nexomaker/registerExportFormat

### Description
Registers a custom export format with the NexoMaker export system, allowing for custom data transformation and file handling.

### Method
POST

### Endpoint
/api/nexomaker/registerExportFormat

### Parameters
#### Request Body
- **config** (object) - Required - Export format configuration object
  - **id** (string) - Required - Unique identifier for the export format
  - **name** (string) - Required - Human-readable display name
  - **transform** (function) - Required - Item transformation function
  - **files** (object) - Optional - File structure configuration
  - **hooks** (object) - Optional - Lifecycle hook implementations

### Request Example
```json
{
  "config": {
    "id": "my_format",
    "name": "My Custom Format",
    "transform": "(item) => ({ /* transformed data */ })",
    "files": "{ /* file configuration */ }",
    "hooks": "{ /* lifecycle hooks */ }"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful registration.

#### Response Example
```json
{
  "message": "Export format 'my_format' registered successfully."
}
```
```

--------------------------------

### Basic useLibraries() Setup in JavaScript

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/imports/libraries

Shows the initial setup required to use the `useLibraries()` utility by including it in the `module.exports` function. This is a prerequisite for importing any libraries.

```javascript
module.exports = ({ useLibraries }) => {
  // Your code here
};
```

--------------------------------

### Nexo Maker Data Model Properties (JavaScript)

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/plugin-expansion/getting-started

Illustrates the core properties guaranteed on normalized items processed by Nexo Maker. These include unique identifiers, display names, item types, and namespace information, essential for consistent data handling.

```javascript
item.id          // string: Unique identifier (e.g., "magic_sword")
item.name        // string: Display name (e.g., "Magic Sword")
item.type        // string: Item type - "item" | "block" | "entity" | "furniture"
item.namespace   // string: Namespace identifier (e.g., "nexo" or custom namespace)
```

--------------------------------

### Simple Keybinding Example

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/imports/libraries/keybinding

Shows a basic implementation of the Keybinding component. It sets up a listener for the 'Ctrl + K' shortcut, which increments a counter when pressed. This example highlights the direct mapping of keys to actions.

```javascript
module.exports = ({ useState, useLibraries }) => {

  const { KeyBinding } = useLibraries();
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>Press <strong>Ctrl + K</strong> to increment: {count}</p>

      <Keybinding
        onKeys={['ctrl+k']}
        onKey={() => setCount(count + 1)}
      />
    </div>
  );
};

```

--------------------------------

### YAML Key Best Practices Examples

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/project-settings

Provides examples of recommended YAML keys for configuration, emphasizing their use for main configuration, environment-specific settings, and server properties. These keys are crucial for saving and loading settings correctly.

```javascript
// ✅ Good - Main configuration
yamlKey: "configs"

// ✅ Good - Environment-specific
yamlKey: "environment"

// ✅ Good - Server properties
yamlKey: "serverProperties"
```

--------------------------------

### Register Custom Export Format (JavaScript)

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/plugin-expansion/getting-started

Demonstrates the minimal configuration to register a custom export format using the Nexo Maker API. This includes defining the format ID, name, and a transform function for item normalization. It assumes the 'api' object is globally available.

```javascript
module.exports.init = async () => {
  api.nexomaker.registerExportFormat({
    id: 'my_plugin',
    name: 'My Plugin Format',
    
    transform: (item) => ({
      item_id: item.id,
      display_name: item.name,
      item_type: item.type,
    }),
  });
};
```

--------------------------------

### Initialize Blockly Workspace with React Hooks

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/imports/libraries/blockly

Sets up a Blockly workspace within a React component using `useRef` for DOM referencing and `useState` for managing code and output. It leverages `useLibraries` to load Blockly and includes placeholders for integration with external APIs. This snippet focuses on the initial setup and state management for a Blockly environment.

```javascript
module.exports = ({ useEffect, useRef, api, usePlaceholders, useState, useLibraries }) => {
  const blocklyDiv = useRef(null);
  const workspace = useRef(null);
  const [code, setCode] = useState('');
  const [output, setOutput] = useState('');
  const placeholders = usePlaceholders();
  const { Blockly } = useLibraries();

  // Example initialization code...
};
```

--------------------------------

### Create App Settings Tab - Complete Example

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/app-settings

A comprehensive example of creating an app settings tab, including various input types like text, checkbox, dropdown, and number. It showcases advanced options like placeholders, descriptions, and input validation.

```javascript
api.nexomaker.postAppSettingsTab({
  id: "expansion-global",
  expansionId: "my_expansion",
  title: "My Expansion",
  description: "Global expansion settings",
  order: 100,
  elements: [
    {
      id: "api-key",
      label: "API Key",
      type: "text",
      placeholder: "XXXX-XXXX-XXXX-XXXX",
      description: "Your API key for external services",
      default: "",
      required: true
    },
    {
      id: "auto-update",
      label: "Automatic Updates",
      type: "checkbox",
      description: "Automatically check for updates",
      default: true
    },
    {
      id: "update-channel",
      label: "Update Channel",
      type: "dropdown",
      options: [
        { value: "stable", label: "Stable" },
        { value: "beta", label: "Beta" },
        { value: "dev", label: "Development" }
      ],
      default: "stable"
    },
    {
      id: "cache-size",
      label: "Cache Size (MB)",
      type: "number",
      min: 10,
      max: 1000,
      default: 100
    }
  ]
});
```

--------------------------------

### useProjectState Summary Example (JavaScript)

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/hooks/useprojectstate

A concise example illustrating the fundamental usage of the useProjectState hook. It shows how to declare a state variable and its corresponding setter function using a unique key and an initial value.

```javascript
const [value, setValue] = useProjectState('my-key', initialValue);
```

--------------------------------

### JavaScript: Logical Ordering of Settings

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/best-practices

Provides an example in JavaScript of how to logically order settings, placing the most important or commonly used ones first, followed by more advanced options, separated by visual breaks.

```javascript
// ✅ Good - Common first, advanced last
elements: [
  { id: "enabled", label: "Enable Feature", type: "checkbox" },
  { id: "mode", label: "Mode", type: "dropdown" },
  { type: "separator" },
  { id: "debug-level", label: "Debug Level", type: "dropdown" },
  { id: "custom-config", label: "Custom Config", type: "textarea" }
]
```

--------------------------------

### Create App Settings Tab - Basic Example

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/app-settings

This snippet demonstrates the basic structure for creating an app settings tab using the NexoMaker API. It defines essential elements like an API key and a feature toggle.

```javascript
api.nexomaker.postAppSettingsTab({
  id: "my-expansion",
  title: "My Expansion",
  description: "Global settings for My Expansion",
  order: 100,
  elements: [
    {
      id: "api-key",
      label: "API Key",
      type: "text",
      placeholder: "Enter your API key",
      default: "",
      required: true
    },
    {
      id: "enabled",
      label: "Enable Feature",
      type: "checkbox",
      default: true
    }
  ]
});
```

--------------------------------

### Setup Project with Specific Logic

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/reading-settings

Illustrates a pattern for setting up project-specific logic by reading configuration from a project's YAML file. If the configuration is loaded successfully and the expansion is enabled within that project, it proceeds to set up the expansion with the project's mode.

```javascript
async function setupProject(project) {
  const config = await api.nexomaker.yaml.read({
    projectID: project.id,
    yamlKey: 'configs'
  });
  
  if (!config.success) {
    console.error('Failed to load project config');
    return;
  }
  
  // Use project-specific settings
  if (config.data['expansion-enabled']) {
    const mode = config.data['expansion-mode'] || 'normal';
    setupExpansion(project, mode);
  }
}
```

--------------------------------

### JavaScript: Consistent Naming Patterns for Settings

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/best-practices

Illustrates the importance of consistent naming patterns for settings in JavaScript to maintain uniformity across an extension. It provides examples of good and bad naming conventions.

```javascript
// ✅ Good - Consistent pattern
"expansion-api-key"
"expansion-api-endpoint"
"expansion-api-timeout"

// ❌ Bad - Inconsistent
"expansionAPIKey"
"api_endpoint"
"timeout-expansion"
```

--------------------------------

### Read JSON Configuration File with JavaScript

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/loaders/load-file

An example of using loadFile() to read a JSON configuration file. It specifies 'utf-8' encoding to get the file content as a string, which is then parsed into a JavaScript object. This pattern is common for loading settings and configurations.

```javascript
const jsonString = await api.nexomaker.loadFile(__dirname + "/config.json", "utf-8");
const config = JSON.parse(jsonString);
```

--------------------------------

### Nexo Maker Console Logging

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/overlay-system/overlay-example

Demonstrates how to log messages to the console using `api.console.log`. This is helpful for debugging and inspecting the state of the application during development. It supports logging strings and objects, and can be used to track the flow of execution.

```javascript
api.console.log('🧪 Testing background APIs...')
```

```javascript
api.console.log('Context:', placeholders.context)
```

```javascript
api.console.log('Project ID:', placeholders.projectId)
```

```javascript
api.console.log('Global data test:', retrievedData)
```

--------------------------------

### JavaScript: Descriptive IDs for Settings

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/best-practices

Demonstrates the use of descriptive and namespaced IDs for settings in JavaScript, emphasizing clarity and avoiding conflicts with other expansions. It contrasts good practices with bad examples.

```javascript
// ✅ Good - Descriptive and namespaced
{ id: "my-expansion-api-key", label: "API Key" }
{ id: "my-expansion-enable-sync", label: "Enable Sync" }
{ id: "my-expansion-max-items", label: "Maximum Items" }

// ❌ Bad - Generic and prone to conflicts
{ id: "key", label: "API Key" }
{ id: "enabled", label: "Enable Sync" }
{ id: "max", label: "Maximum Items" }
```

--------------------------------

### JavaScript: Providing Default Values for Settings

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/best-practices

Explains the necessity of providing sensible default values for all settings in JavaScript to ensure a predictable user experience. It shows examples of settings with and without defaults.

```javascript
// ✅ Good
{
  id: "max-items",
  label: "Maximum Items",
  type: "number",
  min: 1,
  max: 1000,
  default: 100 // Clear default
}

// ❌ Bad
{
  id: "max-items",
  label: "Maximum Items",
  type: "number",
  min: 1,
  max: 1000
  // No default - will be undefined
}
```

--------------------------------

### Animated List with TransitionGroup Example

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/imports/libraries/reacttransitiongroup

Illustrates how to create an animated list where items are added with transitions using TransitionGroup and CSSTransition. This example shows managing a dynamic list of items and animating their appearance.

```javascript
module.exports = ({ useState, useLibraries }) => {

  const { ReactTransitionGroup } = useLibraries();
  const { TransitionGroup, CSSTransition } = ReactTransitionGroup;
  const [items, setItems] = useState(["First", "Second"]);

  return (
    <div>
      <button onClick={() => setItems([...items, "New Item"])}>Add Item</button>
      <TransitionGroup>
        {items.map((item, i) => (
          <CSSTransition key={i} timeout={300} classNames="item">
            <div>{item}</div>
          </CSSTransition>
        ))}
      </TransitionGroup>
    </div>
  );
};
```

--------------------------------

### Modularjs useState Toggle Switch Example

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/hooks/usestate

Illustrates using the useState hook in Modularjs to manage a boolean state for a toggle switch. The example shows how to initialize the state, display its status, and toggle it using a button.

```javascript
module.exports = ({ useState }) => {
  const [isOn, setIsOn] = useState(false);

  return (
    <div>
      <h1>Toggle Switch</h1>
      <p>The switch is <strong>{isOn ? 'ON' : 'OFF'}</strong></p>
      <button onClick={() => setIsOn(!isOn)}>
        {isOn ? 'Turn OFF' : 'Turn ON'}
      </button>
    </div>
  );
};
```

--------------------------------

### Nexo Maker Background API Notifications

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/overlay-system/overlay-example

Demonstrates how to send notifications from the background script using the `api.nexomaker.background.notify` function. This function allows for customizable alerts with different types (success, info, error), titles, messages, durations, and even custom actions.

```javascript
api.nexomaker.background.notify({
  type: 'success',
  title: 'Test Overlay',
  message: 'Statistics reset successfully',
  duration: 2000
});
```

```javascript
api.nexomaker.background.notify({
  type: 'info',
  title: 'Overlay Clicked',
  message: `You clicked the overlay. Total clicks: ${stats.clicks + 1}`
});
```

```javascript
api.nexomaker.background.notify({
  type: 'info',
  title: 'Statistics',
  message: `Clicks: ${stats.clicks}, Toggles: ${stats.toggles}`,
  duration: 5000,
  actions: [
    {
      text: 'Close Statistics',
      onClick: () => { /* logic to close stats */ },
      style: {
        background: 'rgba(255,255,255,0.2)',
        color: 'white',
        border: '1px solid rgba(255,255,255,0.3)',
        padding: '12px 24px',
        borderRadius: '8px',
        cursor: 'pointer',
        fontSize: '14px',
        width: '100%',
        marginTop: '16px'
      }
    }
  ]
});
```

```javascript
api.nexomaker.background.notify({
  type: 'success',
  title: 'API Test Complete',
  message: 'All background APIs working correctly!',
  duration: 3000
});
```

--------------------------------

### Example Usage of postAsset() with Image Conversion - JavaScript

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/themes/themes/replace-assets

This example shows a practical application of posting an asset, specifically an image. It first converts a local image file to a base64 string using `api.nexomaker.imgconvert` and then posts this converted asset using `nm.postAsset()`. Requires the Nexo Maker API and a local image file.

```javascript
const icon = await api.nexomaker.imgconvert(__dirname + "/assets/add-icon.png");

nm.postAsset({
  Add: icon
});
```

--------------------------------

### Nexo Maker Background API Global Data Storage

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/overlay-system/overlay-example

This snippet illustrates the usage of global data storage within the Nexo Maker background script. It shows how to set arbitrary data using `setGlobalData` and retrieve it later with `getGlobalData`. This is useful for persisting state or sharing information between different parts of the extension.

```javascript
api.nexomaker.background.setGlobalData('testData', {
  timestamp: new Date().toISOString(),
  clicks: stats.clicks,
  context: placeholders.context
});
```

```javascript
const retrievedData = api.nexomaker.background.getGlobalData('testData');
```

--------------------------------

### JavaScript Interactive Overlay Component

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/overlay-system/overlay-example

This JavaScript component demonstrates a dynamic overlay with features for visibility toggling, drag-and-drop positioning, and statistics tracking. It utilizes React hooks such as useState, useEffect, and useRef, along with global state management and API calls for notifications and overlay management. It listens for global keyboard shortcuts for enhanced user interaction.

```javascript
/**
 * Test Overlay - Background Module Example
 * This demonstrates a background overlay that runs outside of project context
*/

module.exports = ({ useState, useEffect, useRef, useGlobalState, api, usePlaceholders }) => {
  const [isVisible, setIsVisible] = useGlobalState('overlayVisible', true);
  const [position, setPosition] = useGlobalState('overlayPosition', { x: 100, y: 100 });
  const [isDragging, setIsDragging] = useState(false);
  const [dragOffset, setDragOffset] = useState({ x: 0, y: 0 });
  const [stats, setStats] = useGlobalState('overlayStats', {
    clicks: 0,
    toggles: 0,
    lastInteraction: null
  });
  const overlayRef = useRef(null);
  const placeholders = usePlaceholders();

  // Listen for global keyboard shortcuts
  useEffect(() => {
    const handleKeyPress = (e) => {
      // Ctrl+Shift+O to toggle overlay
      if (e.ctrlKey && e.shiftKey && e.key === 'O') {
        e.preventDefault();
        setIsVisible(prev => {
          const newState = !prev;
          setStats(prev => ({
            ...prev,
            toggles: prev.toggles + 1,
            lastInteraction: new Date().toISOString()
          }));
          
          api.nexomaker.background.notify({
            type: newState ? 'success' : 'info',
            title: 'Test Overlay',
            message: `Overlay ${newState ? 'shown' : 'hidden'} via keyboard shortcut`,
            duration: 2000
          });
          
          return newState;
        });
      }
      
      // Ctrl+Shift+R to reset overlay position
      if (e.ctrlKey && e.shiftKey && e.key === 'R') {
        e.preventDefault();
        setPosition({ x: 100, y: 100 });
        api.nexomaker.background.notify({
          type: 'info',
          title: 'Test Overlay',
          message: 'Position reset to default',
          duration: 2000
        });
      }
    };

    window.addEventListener('keydown', handleKeyPress);
    return () => window.removeEventListener('keydown', handleKeyPress);
  }, []);

  // Handle dragging
  const handleMouseDown = (e) => {
    setIsDragging(true);
    const rect = overlayRef.current.getBoundingClientRect();
    setDragOffset({
      x: e.clientX - rect.left,
      y: e.clientY - rect.top
    });
  };

  useEffect(() => {
    const handleMouseMove = (e) => {
      if (isDragging) {
        setPosition({
          x: e.clientX - dragOffset.x,
          y: e.clientY - dragOffset.y
        });
      }
    };

    const handleMouseUp = () => {
      setIsDragging(false);
    };

    if (isDragging) {
      window.addEventListener('mousemove', handleMouseMove);
      window.addEventListener('mouseup', handleMouseUp);
    }

    return () => {
      window.removeEventListener('mousemove', handleMouseMove);
      window.removeEventListener('mouseup', handleMouseUp);
    };
  }, [isDragging, dragOffset]);

  const handleClick = () => {
    setStats(prev => ({
      ...prev,
      clicks: prev.clicks + 1,
      lastInteraction: new Date().toISOString()
    }));
  };

  const showStatsOverlay = () => {
    api.nexomaker.background.showOverlay('stats-overlay', "
      <div style=\" 
        background: linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%);
        color: white;
        padding: 24px;
        border-radius: 12px;
        box-shadow: 0 8px 32px rgba(0,0,0,0.3);
        max-width: 400px;
        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      \">
        <h3 style=\"margin: 0 0 20px 0; font-size: 18px; font-weight: 600;">
          📊 Test Overlay Statistics
        </h3>
        <div style=\"margin: 12px 0; padding: 16px; background: rgba(255,255,255,0.1); border-radius: 8px;">
          <p style=\"margin: 8px 0;"><strong>Total Clicks:</strong> ${stats.clicks}</p>
          <p style=\"margin: 8px 0;"><strong>Total Toggles:</strong> ${stats.toggles}</p>
          <p style=\"margin: 8px 0;"><strong>Current Position:</strong> (${Math.round(position.x)}, ${Math.round(position.y)})</p>
          <p style=\"margin: 8px 0;"><strong>Last Interaction:</strong> ${stats.lastInteraction ? new Date(stats.lastInteraction).toLocaleString() : 'Never'}</p>
          <p style=\"margin: 8px 0;"><strong>Overlay Visible:</strong> ${isVisible ? '✅ Yes' : '❌ No'}</p>
          <p style=\"margin: 8px 0;"><strong>Context:</strong> ${placeholders.context}</p>
          <p style=\"margin: 8px 0;"><strong>Project ID:</strong> ${placeholders.projectId}</p>
        </div>
        <div style=\"margin-top: 20px; font-size: 12px; opacity: 0.8;">
          <p style=\"margin: 4px 0;">🔥 <strong>Shortcuts:</strong></p>
          <p style=\"margin: 4px 0;">• Ctrl+Shift+O: Toggle overlay</p>
          <p style=\"margin: 4px 0;">• Ctrl+Shift+R: Reset position</p>
          <p style=\"margin: 4px 0;">• Drag to move overlay</p>
        </div>
        <button 
          onclick="window.dispatchEvent(new CustomEvent('modular-hide-overlay', {detail: {overlayId: 'stats-overlay'}}))" 
          style="

```

--------------------------------

### GET /app/settings

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/api-methods

Retrieves all application settings stored in localStorage.

```APIDOC
## GET /app/settings

### Description
Get all app settings as a key-value object stored in localStorage.

### Method
GET

### Endpoint
/app/settings

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const settings = api.nexomaker.getAppSettings();
const apiKey = settings['api-key'] || '';
const enabled = settings['enable-feature'] || false;
```

### Response
#### Success Response (200)
- **Object** - Settings object from localStorage

#### Response Example
```json
{
  "api-key": "your_api_key",
  "enable-feature": true,
  "some-other-setting": "value"
}
```
```

--------------------------------

### JavaScript: Adding Validation Constraints to Settings

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/best-practices

Shows how to implement input validation for settings in JavaScript using constraints like `min`, `max`, and `pattern` to prevent invalid user input. It provides validated and unvalidated examples.

```javascript
// ✅ Good - Validated
{
  id: "port",
  label: "Port Number",
  type: "number",
  min: 1,
  max: 65535,
  default: 8080,
  description: "Port must be between 1 and 65535"
}

{
  id: "email",
  label: "Email",
  type: "text",
  pattern: "^[^"]+@[^"]+\\.[^"]+$",
  placeholder: "user@example.com"
}

// ❌ Bad - No validation
{
  id: "port",
  label: "Port Number",
  type: "number" // Could be negative or > 65535
}
```

--------------------------------

### Run Generated Blockly Code with Output Capture

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/imports/libraries/blockly

This function executes the JavaScript code generated from the Blockly workspace. It captures any output sent to `console.log` during execution and displays it. Error handling is included to catch and report runtime errors. This allows for interactive testing of the visual programs.

```javascript
const runCode = () => {
    if (!code.trim()) {
      setOutput('No code to run');
      return;
    }

    try {
      // Capture console.log output
      const originalLog = console.log;
      let capturedOutput = '';
      
      console.log = (...args) => {
        capturedOutput += args.join(' ') + '\n';
        originalLog(...args);
      };

      // Execute the generated code
      eval(code);

      // Restore original console.log
      console.log = originalLog;

      setOutput(capturedOutput || 'Code executed successfully (no output)');
      api.console.log('Blockly code executed:', code);
    } catch (error) {
      setOutput(`Error: ${error.message}`);
      api.console.error('Blockly execution error:', error);
    }
  };
```

--------------------------------

### Initialize Blockly with Custom Theme and Toolbox in JavaScript

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/imports/libraries/blockly

This JavaScript code initializes a Blockly workspace with a custom dark theme and a toolbox. It defines a dark theme for Blockly and injects the workspace into a specified div element. The toolbox includes categories for logic, loops, math, and text, with various blocks within each category.

```javascript
module.exports = ({ useEffect, useRef, api, usePlaceholders, useState, useLibraries }) => {
  const blocklyDiv = useRef(null);
  const workspace = useRef(null);
  const [code, setCode] = useState('');
  const [output, setOutput] = useState('');
  const placeholders = usePlaceholders();
  const { Blockly } = useLibraries();

  useEffect(() => {
    if (blocklyDiv.current && Blockly) {
      // Create custom dark theme
      const darkTheme = Blockly.Theme.defineTheme('dark', {
        'base': Blockly.Themes.Classic,
        'componentStyles': {
          'workspaceBackgroundColour': '#1e1e1e',
          'toolboxBackgroundColour': '#333333',
          'toolboxForegroundColour': '#ffffff',
          'flyoutBackgroundColour': '#252526',
          'flyoutForegroundColour': '#cccccc',
          'flyoutOpacity': 0.9,
          'scrollbarColour': '#484848',
          'insertionMarkerColour': '#ffffff',
          'insertionMarkerOpacity': 0.3,
          'markerColour': '#fff200',
          'cursorColour': '#d0d0d0',
          'selectedGlowColour': '#ffffff',
          'selectedGlowOpacity': 0.3,
          'replacementGlowColour': '#fff200',
          'replacementGlowOpacity': 0.3
        },
        'blockStyles': {
          'colour_blocks': {
            'colourPrimary': '#a55b80',
            'colourSecondary': '#ad73a6',
            'colourTertiary': '#9c2d69'
          },
          'list_blocks': {
            'colourPrimary': '#745ba5',
            'colourSecondary': '#9085db',
            'colourTertiary': '#6c4ce6'
          },
          'logic_blocks': {
            'colourPrimary': '#5b80a5',
            'colourSecondary': '#73a6ad',
            'colourTertiary': '#2d699c'
          },
          'loop_blocks': {
            'colourPrimary': '#5ba55b',
            'colourSecondary': '#6bb36b',
            'colourTertiary': '#498949'
          },
          'math_blocks': {
            'colourPrimary': '#5b67a5',
            'colourSecondary': '#6c82c7',
            'colourTertiary': '#3e56a6'
          },
          'procedure_blocks': {
            'colourPrimary': '#995ba5',
            'colourSecondary': '#b373c7',
            'colourTertiary': '#8c4ca6'
          },
          'text_blocks': {
            'colourPrimary': '#5ba58c',
            'colourSecondary': '#73c7a6',
            'colourTertiary': '#4ca686'
          },
          'variable_blocks': {
            'colourPrimary': '#a55b99',
            'colourSecondary': '#c773b3',
            'colourTertiary': '#a64c8c'
          }
        }
      });

      // Initialize Blockly workspace
      workspace.current = Blockly.inject(blocklyDiv.current, {
        theme: darkTheme,
        toolbox: {
          kind: 'categoryToolbox',
          contents: [
            {
              kind: 'category',
              name: 'Logic',
              colour: 210,
              contents: [
                {
                  kind: 'block',
                  type: 'controls_if'
                },
                {
                  kind: 'block',
                  type: 'logic_compare'
                },
                {
                  kind: 'block',
                  type: 'logic_operation'
                },
                {
                  kind: 'block',
                  type: 'logic_negate'
                },
                {
                  kind: 'block',
                  type: 'logic_boolean'
                }
              ]
            },
            {
              kind: 'category',
              name: 'Loops',
              colour: 120,
              contents: [
                {
                  kind: 'block',
                  type: 'controls_repeat_ext'
                },
                {
                  kind: 'block',
                  type: 'controls_whileUntil'
                },
                {
                  kind: 'block',
                  type: 'controls_for'
                }
              ]
            },
            {
              kind: 'category',
              name: 'Math',
              colour: 230,
              contents: [
                {
                  kind: 'block',
                  type: 'math_number'
                },
                {
                  kind: 'block',
                  type: 'math_arithmetic'
                },
                {
                  kind: 'block',
                  type: 'math_single'
                },
                {
                  kind: 'block',
                  type: 'math_trig'
                },
                {
                  kind: 'block',
                  type: 'math_constant'
                }
              ]
            },
            {
              kind: 'category',
              name: 'Text',
              colour: 160,
              contents: [
                {
                  kind: 'block',
                  type: 'text'
                },
                {
                  kind: 'block',

```

--------------------------------

### React Button: Test Notification

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/overlay-system/overlay-example

A React button component to send a test notification using the Nexo Maker API. It displays information about the number of clicks and the current context. Requires the Nexo Maker API and React.

```javascript
onClick={(e) => {
            e.stopPropagation();
            api.nexomaker.background.notify({
              type: 'info',
              title: 'Test Notification',
              message: `Overlay clicked ${stats.clicks} times! Running in ${placeholders.context} context`,
              duration: 4000
            });
          }}
```

--------------------------------

### Initialize Blockly Workspace and Define Custom Block

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/imports/libraries/blockly

This snippet initializes a Blockly workspace with predefined categories and grid settings. It also defines a custom 'console_log' block, including its visual appearance and the JavaScript code generation logic for it. This allows users to create visual programs that can output messages to the console.

```javascript
const workspace = Blockly.inject('blocklyDiv', {
    toolbox: {
      kind: 'xml',
      contents: [
        {
          kind: 'category',
          name: 'Text',
          colour: 160,
          contents: [
            {
              kind: 'block',
              type: 'text_join'
            },
            {
              kind: 'block',
              type: 'text_append'
            },
            {
              kind: 'block',
              type: 'text_length'
            },
            {
              kind: 'block',
              type: 'text_isEmpty'
            }
          ]
        },
        {
          kind: 'category',
          name: 'Variables',
          colour: 330,
          custom: 'VARIABLE'
        },
        {
          kind: 'category',
          name: 'Functions',
          colour: 290,
          custom: 'PROCEDURE'
        },
        {
          kind: 'category',
          name: 'Console',
          colour: 65,
          contents: [
            {
              kind: 'block',
              type: 'console_log'
            }
          ]
        }
      ]
    },
    grid: {
      spacing: 20,
      length: 3,
      colour: '#ccc',
      snap: true
    },
    zoom: {
      controls: true,
      wheel: true,
      startScale: 1.0,
      maxScale: 3,
      minScale: 0.3,
      scaleSpeed: 1.2
    },
    trashcan: true
  });

  // Define custom console log block
  if (Blockly.Blocks) {
    Blockly.Blocks['console_log'] = {
      init: function() {
        this.appendValueInput('MESSAGE')
            .setCheck(null)
            .appendField('console log');
        this.setPreviousStatement(true, null);
        this.setNextStatement(true, null);
        this.setColour(65);
        this.setTooltip('Log a message to the console');
        this.setHelpUrl('');
      }
    };

    // JavaScript code generator for console log
      if (Blockly.JavaScript) {
      Blockly.JavaScript['console_log'] = function(block) {
        const message = Blockly.JavaScript.valueToCode(block, 'MESSAGE', Blockly.JavaScript.ORDER_ATOMIC);
        return `console.log(${message});\n`;
      };
    }
  }

  // Listen for workspace changes
  workspace.current.addChangeListener(() => {
    generateCode();
  });

  api.console.log('Blockly workspace initialized');
```

--------------------------------

### React Overlay Component with State Management

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/overlay-system/overlay-example

This React component renders an interactive overlay for testing and debugging. It manages UI visibility, drag-and-drop functionality, and displays statistics. It utilizes `useState` for managing click and toggle counts, and `useRef` for DOM element referencing. The overlay's appearance and behavior are controlled via inline styles and event handlers.

```javascript
const Overlay = ({ isVisible, setIsVisible, position, setPosition, placeholders, api, ... }) => {
  const overlayRef = useRef(null);
  const [isDragging, setIsDragging] = useState(false);
  const [stats, setStats] = useState({
    clicks: 0,
    toggles: 0,
    lastInteraction: null
  });

  const handleMouseDown = (e) => {
    e.preventDefault();
    setIsDragging(true);
    document.addEventListener('mousemove', handleMouseMove);
    document.addEventListener('mouseup', handleMouseUp);
  };

  const handleMouseMove = (e) => {
    if (!isDragging) return;
    setPosition({
      x: e.clientX - overlayRef.current.getBoundingClientRect().left,
      y: e.clientY - overlayRef.current.getBoundingClientRect().top
    });
  };

  const handleMouseUp = () => {
    setIsDragging(false);
    document.removeEventListener('mousemove', handleMouseMove);
    document.removeEventListener('mouseup', handleMouseUp);
  };

  const handleClick = () => {
    setStats(prev => ({ ...prev, clicks: prev.clicks + 1, lastInteraction: 'click' }));
    api.nexomaker.background.notify({
      type: 'info',
      title: 'Overlay Clicked',
      message: `You clicked the overlay. Total clicks: ${stats.clicks + 1}`
    });
  };

  const showStatsOverlay = () => {
    api.nexomaker.background.notify({
      type: 'info',
      title: 'Statistics',
      message: `Clicks: ${stats.clicks}, Toggles: ${stats.toggles}`,
      duration: 5000,
      // Custom close button example
      actions: [
        {
          text: 'Close Statistics',
          onClick: () => { /* logic to close stats */ },
          style: {
            background: 'rgba(255,255,255,0.2)',
            color: 'white',
            border: '1px solid rgba(255,255,255,0.3)',
            padding: '12px 24px',
            borderRadius: '8px',
            cursor: 'pointer',
            fontSize: '14px',
            width: '100%',
            marginTop: '16px'
          }
        }
      ]
    });
  };

  const resetStats = () => {
    setStats({
      clicks: 0,
      toggles: 0,
      lastInteraction: null
    });
    api.nexomaker.background.notify({
      type: 'success',
      title: 'Test Overlay',
      message: 'Statistics reset successfully',
      duration: 2000
    });
  };

  const testBackgroundApis = () => {
    api.console.log('🧪 Testing background APIs...');
    api.console.log('Context:', placeholders.context);
    api.console.log('Project ID:', placeholders.projectId);
    
    // Test global data storage
    api.nexomaker.background.setGlobalData('testData', {
      timestamp: new Date().toISOString(),
      clicks: stats.clicks,
      context: placeholders.context
    });
    
    const retrievedData = api.nexomaker.background.getGlobalData('testData');
    api.console.log('Global data test:', retrievedData);
    
    api.nexomaker.background.notify({
      type: 'success',
      title: 'API Test Complete',
      message: 'All background APIs working correctly!',
      duration: 3000
    });
  };

  if (!isVisible) {
    return null;
  }

  return (
    <div 
      ref={overlayRef}
      className="interactive"
      style={{
        position: 'fixed',
        left: `${position.x}px`,
        top: `${position.y}px`,
        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
        color: 'white',
        padding: '16px',
        borderRadius: '12px',
        boxShadow: '0 8px 32px rgba(0,0,0,0.3)',
        cursor: isDragging ? 'grabbing' : 'grab',
        userSelect: 'none',
        zIndex: 2000,
        minWidth: '280px',
        border: '1px solid rgba(255,255,255,0.2)',
        backdropFilter: 'blur(10px)'
      }}
      onMouseDown={handleMouseDown}
      onClick={handleClick}
    >
      <div style={{ marginBottom: '12px', display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
        <h4 style={{ margin: 0, fontSize: '16px', fontWeight: '600' }}>
          🧪 Test Overlay ({placeholders.context})
        </h4>
        <button
          onClick={(e) => {
            e.stopPropagation();
            setIsVisible(false);
          }}
          style={{
            background: 'rgba(255,255,255,0.2)',
            border: 'none',
            color: 'white',
            width: '24px',
            height: '24px',
            borderRadius: '50%',
            cursor: 'pointer',
            fontSize: '14px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}
        >
          ×
        </button>
      </div>
      
      <div style={{ fontSize: '14px', marginBottom: '12px', opacity: 0.9 }}>
        Background overlay running in {placeholders.context} context
      </div>
      
      <div style={{ 
        background: 'rgba(255,255,255,0.1)', 
        padding: '12px', 
        borderRadius: '8px', 
        marginBottom: '12px',
        fontSize: '12px'
      }}>
        <div>📊 Clicks: {stats.clicks}</div>
        <div>🔄 Toggles: {stats.toggles}</div>
        <div>📍 Position: ({Math.round(position.x)}, {Math.round(position.y)})</div>
        <div>🎯 Project: {placeholders.projectId}</div>
      </div>
      
      <div style={{ display: 'flex', gap: '8px', flexDirection: 'column' }}>
        <button
          onClick={(e) => {
            e.stopPropagation();
            showStatsOverlay();
          }}
          style={{
            background: 'rgba(255,255,255,0.2)',
            border: '1px solid rgba(255,255,255,0.3)',
            color: 'white',
            padding: '8px 12px',
            borderRadius: '6px',
            cursor: 'pointer',
            fontSize: '12px'
          }}
        >
          📊 Show Statistics
        </button>
        
        <button
          onClick={(e) => {
            e.stopPropagation();
            testBackgroundApis();
          }}
          style={{
            background: 'rgba(16, 185, 129, 0.3)',
            border: '1px solid rgba(16, 185, 129, 0.5)',
            color: 'white',
            padding: '8px 12px',
            borderRadius: '6px',
            cursor: 'pointer',
            fontSize: '12px'
          }}
        >
          🧪 Test Background APIs
        </button>
        
        <button
          onClick={(e) => {
            e.stopPropagation();
            resetStats();
          }}
          style={{
            background: 'rgba(239, 68, 68, 0.3)',
            border: '1px solid rgba(239, 68, 68, 0.5)',
            color: 'white',
            padding: '8px 12px',
            borderRadius: '6px',
            cursor: 'pointer',
            fontSize: '12px'
          }}
        >
          🔄 Reset Statistics
        </button>
      </div>
    </div>
  );
};
```

--------------------------------

### Global State Management for Overlays in Nexo Maker

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/overlay-system

Shows how to use the `useGlobalState` hook provided by Nexo Maker for managing persistent state within overlays. This state survives route changes and application restarts, ensuring data continuity. Examples include managing visibility and position of an overlay.

```javascript
const [isVisible, setIsVisible] = useGlobalState('overlayVisible', true);
const [position, setPosition] = useGlobalState('overlayPosition', { x: 100, y: 100 });
```

--------------------------------

### Define Project Settings Element: Clear Labels and Descriptions

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/project-settings

Illustrates the definition of a single project settings element, focusing on providing clear labels and descriptions for user understanding. This example shows a number input for maximum entities with defined min, max, and default values.

```javascript
{
  id: "max-entities",
  label: "Maximum Entities",
  type: "number",
  description: "Maximum number of custom entities per chunk",
  min: 1,
  max: 100,
  default: 10
}
```

--------------------------------

### JavaScript: Basic Item Transformation

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/plugin-expansion/transform-function

A fundamental example of the transform function in JavaScript. It maps basic properties like id, name, and type from a normalized item object to a new object for export. This serves as a starting point for more complex transformations.

```javascript
transform: (item) => ({
  id: item.id,
  name: item.name,
  type: item.type,
})
```

--------------------------------

### Accessing Nexo Maker API and Loading Assets (JavaScript)

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/getting-started/basic-concepts/starting-a-expansion

Demonstrates how to create a shorthand reference for the Nexo Maker API and use it to load assets within your expansion. The `api.nexomaker` object provides access to various platform functions. __dirname helps in resolving the asset path relative to the current expansion file.

```javascript
const nm = api.nexomaker;
const customIMG = await nm.loadAsset(__dirname + "/assets/customImg.png");
```

--------------------------------

### Fade Animation with CSSTransition Example

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/modular/imports/libraries/reacttransitiongroup

Provides an example of implementing a fade-in/fade-out animation using the CSSTransition component. It includes a button to toggle the visibility of an element and the corresponding CSS classes for the transition.

```javascript
module.exports = ({ useState, useLibraries }) => {

  const { ReactTransitionGroup } = useLibraries();
  const { CSSTransition } = ReactTransitionGroup;
  const [show, setShow] = useState(false);

  return (
    <div>
      <button onClick={() => setShow(!show)}>Toggle</button>
      <CSSTransition in={show} timeout={300} classNames="fade" unmountOnExit>
        <div className="fade">Hello with Fade</div>
      </CSSTransition>
    </div>
  );
};
```

```css
.fade-enter { opacity: 0; }
.fade-enter-active { opacity: 1; transition: opacity 300ms; }
.fade-exit { opacity: 1; }
.fade-exit-active { opacity: 0; transition: opacity 300ms; }
```

--------------------------------

### Document Complex Settings with Descriptions and Hints

Source: https://nexo-maker.gitbook.io/nexo-maker-docs/main.js/api/settings/best-practices

Provides guidance on documenting complex configuration settings, such as those requiring YAML format. It shows how to combine `description`, `hint`, and `placeholder` for clarity.

```javascript
// ✅ Good
{
  id: "custom-config",
  label: "Custom Configuration",
  type: "textarea",
  description: "Advanced YAML configuration. Use with caution!",
  hint: "Example:\nkey: value\nlist:\n  - item1\n  - item2",
  placeholder: "Enter YAML configuration..."
}
```
Tokens:
Raw