Project Settings

Project Settings are project-specific settings that can vary between different projects. They are stored in the project's YAML files.

---

Overview

Storage Location

Project settings can be saved to different YAML sections:

YAML Key	File/Section	Use Case
configs	config.yml	Main project configuration
environment	Environment config	Environment-specific settings
serverProperties	Server properties	Minecraft server properties format

Key Characteristics

• Scope: Per-project

• Format: YAML

• Persistence: Stored in project files

• Isolation: Each project has independent settings

---

Section Types

type: "settings"

Standard form with configurable elements.

api.nexomaker.postProjectSettingsTab({
  id: "expansion-settings",
  title: "Expansion Settings",
  type: "settings",
  yamlKey: "configs",
  elements: [
    {
      id: "enabled",
      label: "Enable Feature",
      type: "checkbox",
      default: true
    }
  ]
});

type: "category"

Visual category header for organizing tabs.

api.nexomaker.postProjectSettingsTab({
  type: "category",
  title: "MY EXPANSION",
  id: "my-category",
  order: 10
});

type: "separator"

Horizontal divider line between sections.

api.nexomaker.postProjectSettingsTab({
  type: "separator",
  id: "my-separator",
  order: 20
});

type: "custom"

Custom HTML rendering with full control.

api.nexomaker.postProjectSettingsTab({
  id: "custom-section",
  title: "Custom UI",
  type: "custom",
  render: (project, values) => {
    return `<div>Custom HTML here</div>`;
  }
});

---

Creating Project Settings

Basic Example

api.nexomaker.postProjectSettingsTab({
  id: "expansion-config",
  title: "Configuration",
  type: "settings",
  yamlKey: "configs",
  order: 50,
  elements: [
    {
      id: "mode",
      label: "Mode",
      type: "dropdown",
      options: [
        { value: "normal", label: "Normal" },
        { value: "advanced", label: "Advanced" }
      ],
      default: "normal"
    }
  ]
});

Organized Example with Categories

// Category header
api.nexomaker.postProjectSettingsTab({
  type: "category",
  title: "MY EXPANSION",
  id: "expansion-category",
  order: 50
});

// General settings
api.nexomaker.postProjectSettingsTab({
  id: "expansion-general",
  title: "General",
  type: "settings",
  yamlKey: "configs",
  order: 51,
  elements: [
    {
      id: "enabled",
      label: "Enable Expansion",
      type: "checkbox",
      default: true
    },
    {
      id: "feature-level",
      label: "Feature Level",
      type: "dropdown",
      options: [
        { value: "basic", label: "Basic" },
        { value: "standard", label: "Standard" },
        { value: "premium", label: "Premium" }
      ],
      default: "standard"
    }
  ]
});

// Advanced settings
api.nexomaker.postProjectSettingsTab({
  id: "expansion-advanced",
  title: "Advanced",
  type: "settings",
  yamlKey: "configs",
  order: 52,
  elements: [
    {
      id: "debug-mode",
      label: "Debug Mode",
      type: "checkbox",
      default: false
    },
    {
      id: "custom-config",
      label: "Custom Configuration",
      type: "textarea",
      rows: 6,
      placeholder: "Enter YAML configuration...",
      default: ""
    }
  ]
});

// Separator
api.nexomaker.postProjectSettingsTab({
  type: "separator",
  id: "expansion-separator",
  order: 53
});

---

Reading Project Settings

Using YAML API

async function getProjectSettings(projectId) {
  try {
    // Read from config.yml
    const response = await api.nexomaker.yaml.read({
      projectID: projectId,
      yamlKey: 'configs'
    });
    
    if (response.success) {
      const enabled = response.data['enabled'] || false;
      const featureLevel = response.data['feature-level'] || 'standard';
      return { enabled, featureLevel };
    }
  } catch (error) {
    console.error('Failed to read project settings:', error);
  }
  
  return null;
}

// Usage
const settings = await getProjectSettings(currentProject.id);
if (settings.enabled) {
  enableFeature(settings.featureLevel);
}

Reading from Different YAML Keys

// Read from configs
const configs = await api.nexomaker.yaml.read({
  projectID: projectId,
  yamlKey: 'configs'
});

// Read from environment
const env = await api.nexomaker.yaml.read({
  projectID: projectId,
  yamlKey: 'environment'
});

// Read from serverProperties
const serverProps = await api.nexomaker.yaml.read({
  projectID: projectId,
  yamlKey: 'serverProperties'
});

---

Custom Sections

For advanced UIs, create custom HTML rendering:

const dashboardRenderer = (project, values) => {
  const totalItems = project?.items?.length || 0;
  const expansionItems = project?.items?.filter(item => 
    item.yamlData?.modules?.myExpansion
  ).length || 0;
  
  return `
    <div class="custom-dashboard" style="padding: 20px;">
      <h2>Expansion Dashboard</h2>
      
      <div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 16px; margin: 20px 0;">
        <div style="background: var(--col-accent-col); padding: 16px; border-radius: var(--radius-md);">
          <h3 style="color: var(--col-txt-secondary); margin: 0;">Total Items</h3>
          <p style="font-size: 32px; color: var(--col-txt-primary); margin: 8px 0 0 0;">${totalItems}</p>
        </div>
        <div style="background: var(--col-accent-col); padding: 16px; border-radius: var(--radius-md);">
          <h3 style="color: var(--col-txt-secondary); margin: 0;">Expansion Items</h3>
          <p style="font-size: 32px; color: var(--col-txt-primary); margin: 8px 0 0 0;">${expansionItems}</p>
        </div>
      </div>
      
      <button 
        onclick="exportData('${project.id}')"
        style="padding: 8px 16px; background: var(--col-primary-form); color: white; border: none; border-radius: var(--radius-sm); cursor: pointer;"
      >
        Export Data
      </button>
    </div>
  `;
};

api.nexomaker.postProjectSettingsTab({
  id: "dashboard",
  title: "Dashboard",
  type: "custom",
  order: 10,
  render: dashboardRenderer
});

---

Best Practices

1. Use Appropriate YAML Keys

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

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

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

2. Organize with Categories

// Use categories to group related settings
api.nexomaker.postProjectSettingsTab({
  type: "category",
  title: "MY EXPANSION",
  order: 50
});

// Follow with your settings tabs
api.nexomaker.postProjectSettingsTab({
  id: "general",
  title: "General",
  type: "settings",
  order: 51,
  /* ... */
});

3. Provide Clear Labels

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

4. Use Separators

// Add separators between logical groups
api.nexomaker.postProjectSettingsTab({
  type: "separator",
  id: "separator-1",
  order: 59
});

---

Common Patterns

Feature Configuration

elements: [
  {
    id: "enabled",
    label: "Enable Feature",
    type: "checkbox",
    default: true
  },
  {
    id: "mode",
    label: "Mode",
    type: "dropdown",
    options: [
      { value: "simple", label: "Simple" },
      { value: "advanced", label: "Advanced" }
    ],
    default: "simple"
  },
  {
    id: "max-items",
    label: "Maximum Items",
    type: "number",
    min: 1,
    max: 1000,
    default: 100
  }
]

Debug Settings

elements: [
  {
    id: "debug-mode",
    label: "Debug Mode",
    type: "checkbox",
    default: false,
    description: "Enable detailed logging"
  },
  {
    id: "log-level",
    label: "Log Level",
    type: "dropdown",
    options: [
      { value: "error", label: "Error" },
      { value: "warn", label: "Warning" },
      { value: "info", label: "Info" },
      { value: "debug", label: "Debug" }
    ],
    default: "info"
  },
  {
    id: "verbose-output",
    label: "Verbose Output",
    type: "checkbox",
    default: false
  }
]

---

Troubleshooting

Settings Not Saving

Problem: Settings don't persist.

Solutions:

1. Verify yamlKey is valid ('configs', 'environment', or 'serverProperties')

2. Check console for YAML write errors

3. Ensure element IDs don't conflict with existing keys

Settings Not Loading

Problem: Can't read settings values.

Solutions:

1. Use correct yamlKey when reading

2. Provide fallback values

3. Check if project is loaded correctly

---

Next Steps

• Learn about Element Types →

• Create Custom Elements →

• See complete examples →