Editors

Editors are pages used to edit elements in the project. They're connected to a Creator and Element Type. This gives you the option to create custom editors and new content in Nexo Ma

Registration (main.js)

api.nexomaker.registerEditorType(editorId, componentPath, metadata)

Location: Call this in your expansion's main.js init() function.

Registers a custom editor component that can be used to edit specific element types.

Parameters

Parameter	Type	Required	Description
editorId	string	Yes	Unique identifier for this editor
componentPath	string	Yes	Absolute path to .jsx file (use __dirname + '/path/file.jsx')
metadata	object	No	Additional metadata about the editor

Metadata Object

Property	Type	Description
label	string	Display name for the editor
description	string	Brief description of what this editor does

Returns

void

Example (main.js)

module.exports.init = async () => {
  // Register the custom editor
  api.nexomaker.registerEditorType(
    'armor_editor',
    __dirname + '/editors/ArmorEditor.jsx',  // Use __dirname + string concatenation (NOT path.join)
    {
      label: 'Armor Editor',
      description: 'Edit armor pieces with custom stats'
    }
  );
};

---

Mapping Types to Editors (main.js)

api.nexomaker.setEditorForType(elementType, editorId)

Location: Call this in your expansion's main.js init() function.

Maps an element type to use your custom editor instead of the default editor.

Parameters

Parameter	Type	Description
elementType	string	The element type ID (e.g., 'armor', 'weapon')
editorId	string	The editor ID you registered

Example (main.js)

module.exports.init = async () => {
  // Step 1: Register editor
  api.nexomaker.registerEditorType(
    'armor_editor',
    __dirname + '/editors/ArmorEditor.jsx',
    { label: 'Armor Editor' }
  );
  
  // Step 2: Map 'armor' type to use the armor editor
  api.nexomaker.setEditorForType('armor', 'armor_editor');
};

---

Editor Component Structure (.jsx file)

Function Signature

Important:

• Use export default function (NOT module.exports)

• All hooks are passed as props, NOT imported

• No import statements allowed

export default function MyEditor({ 
  api,              // Sandboxed API
  useState,         // Passed as prop - NO IMPORT
  useEffect,        // Passed as prop - NO IMPORT
  useMemo,          // Passed as prop - NO IMPORT
  useRef,           // Passed as prop - NO IMPORT
  projectId,        // Current project ID
  itemData,         // Full item object with path, data, pack
  itemId,           // Item ID being edited
  content,          // Array of all items
  setContent,       // Function to update content array
  useComponents,    // Access to NexoMaker components
  useWindow,        // Window controls
  useGlobalState,   // Global state management
  useProjectState   // Project-specific state
}) {
  // Component logic
  return (
    <div data-modular-id="my_editor">
      {/* UI */}
    </div>
  );
}

Item Data

itemData: {
  path: string           // Absolute path to YAML file
  data: {                // Parsed YAML content
    id: string
    type: string
    // ... all YAML fields
  }
  pack: string           // Pack name
}

itemId: string           // ID of the item being edited

Content Management

content: Array<{         // Array of all items in project
  path: string
  data: object
  pack: string
}>

setContent: (newContent: Array<any>) => void  // Update content array (for UI sync)

---

Best Practices

1. No Imports - Use Props

// ❌ WRONG - Don't import hooks (this will fail)
import { useState, useEffect } from 'react';

// ✅ CORRECT - Hooks are passed as props
export default function MyEditor({ useState, useEffect, api, ... }) {
  const [state, setState] = useState(initialValue);
  // ...
}

2. Always Show Loading States

export default function MyEditor({ useState, useEffect, api, projectId }) {
  const [loading, setLoading] = useState(true);
  const [items, setItems] = useState([]);

  useEffect(() => {
    async function loadData() {
      setLoading(true);
      try {
        const data = await api.nexomaker.item.readAll(projectId);
        setItems(data);
      } catch (error) {
        api.console.error('Failed to load:', error);
      } finally {
        setLoading(false);
      }
    }
    loadData();
  }, [projectId]);

  if (loading) {
    return <div>Loading...</div>;
  }

  return <div>{/* content */}</div>;
}

3. Handle Missing Data Gracefully

export default function MyEditor({ useEffect, useState, api, itemData }) {
  const [formData, setFormData] = useState({});
  
  useEffect(() => {
    if (itemData && itemData.data) {
      setFormData(itemData.data);
    } else {
      api.console.warn('No item data available');
      setFormData({}); // Use empty defaults
    }
  }, [itemData]);
}

4. Validate Before Saving

const handleSave = async () => {
  // Validation
  if (!armorData.name) {
    api.console.error('Name is required');
    return;
  }
  
  if (armorData.defense < 0 || armorData.defense > 20) {
    api.console.error('Defense must be between 0 and 20');
    return;
  }
  
  // Save
  await api.nexomaker.item.update({ ... });
};

5. Provide User Feedback

export default function MyEditor({ useState, api, useComponents, itemData }) {
  const { Button } = useComponents();
  const [saved, setSaved] = useState(false);
  const [error, setError] = useState(null);

  const handleSave = async () => {
    setError(null);
    try {
      await api.nexomaker.item.update({ path: itemData.path, changes: {...} });
      setSaved(true);
      setTimeout(() => setSaved(false), 2000);
    } catch (err) {
      setError(err.message);
      api.console.error('Save failed:', err);
    }
  };

  return (
    <div>
      <Button onClick={handleSave}>Save</Button>
      {saved && <span style={{color: 'green'}}>✅ Saved!</span>}
      {error && <span style={{color: 'red'}}>❌ {error}</span>}
    </div>
  );
}

6. Use Scoped Logging

// All console methods are automatically scoped
api.console.log('This appears as [Modular-armor_editor] message');
api.console.warn('Warning message');
api.console.error('Error message');

7. Update Content Array After Save

const handleSave = async () => {
  // Save to YAML
  await api.nexomaker.item.update({ path: itemData.path, changes });
  
  // Update UI immediately (don't wait for reload)
  const updatedContent = content.map(item => {
    if (item.data?.id === itemId) {
      return { ...item, data: { ...item.data, ...changes } };
    }
    return item;
  });
  setContent(updatedContent);
};

---

Advanced Patterns

Auto-Save

export default function MyEditor({ useState, useEffect, api, itemData }) {
  const [formData, setFormData] = useState({});
  const [saveTimeout, setSaveTimeout] = useState(null);

  // Auto-save after 1 second of no changes
  useEffect(() => {
    if (saveTimeout) {
      clearTimeout(saveTimeout);
    }
    
    const timeout = setTimeout(async () => {
      await api.nexomaker.item.update({
        path: itemData.path,
        changes: formData
      });
      api.console.log('Auto-saved');
    }, 1000);
    
    setSaveTimeout(timeout);
    
    return () => clearTimeout(timeout);
  }, [formData]);
}

Multi-Section Form

export default function MyEditor({ useState, useComponents }) {
  const { Button } = useComponents();
  const [activeSection, setActiveSection] = useState('basic');
  
  return (
    <div data-modular-id="my_editor">
      <div className="tabs">
        <Button onClick={() => setActiveSection('basic')}>Basic</Button>
        <Button onClick={() => setActiveSection('advanced')}>Advanced</Button>
        <Button onClick={() => setActiveSection('mechanics')}>Mechanics</Button>
      </div>
      
      {activeSection === 'basic' && <BasicSection />}
      {activeSection === 'advanced' && <AdvancedSection />}
      {activeSection === 'mechanics' && <MechanicsSection />}
    </div>
  );
}

Undo/Redo Support

export default function MyEditor({ useState, api, itemData }) {
  const [history, setHistory] = useState([]);
  const [historyIndex, setHistoryIndex] = useState(-1);
  const [formData, setFormData] = useState({});
  
  const updateFormData = (newData) => {
    // Add to history
    const newHistory = history.slice(0, historyIndex + 1);
    newHistory.push(newData);
    setHistory(newHistory);
    setHistoryIndex(newHistory.length - 1);
    setFormData(newData);
  };
  
  const undo = () => {
    if (historyIndex > 0) {
      setHistoryIndex(historyIndex - 1);
      setFormData(history[historyIndex - 1]);
    }
  };
  
  const redo = () => {
    if (historyIndex < history.length - 1) {
      setHistoryIndex(historyIndex + 1);
      setFormData(history[historyIndex + 1]);
    }
  };
}

---

Debugging

Check itemData Structure

export default function MyEditor({ useEffect, api, itemData }) {
  useEffect(() => {
    api.console.log('itemData received:', itemData);
    api.console.log('itemData.path:', itemData?.path);
    api.console.log('itemData.data:', itemData?.data);
  }, [itemData]);
}

Verify Save Calls

const handleSave = async () => {
  api.console.log('Saving with path:', itemData.path);
  api.console.log('Changes:', changes);
  
  try {
    await api.nexomaker.item.update({ path: itemData.path, changes });
    api.console.log('✅ Save successful');
  } catch (error) {
    api.console.error('❌ Save failed:', error);
  }
};

---