Contributing

The Brain grows through community contributions. Three ways to help:

1. Accept good Blueprints in the plugin. They flow back automatically.
2. Submit node references + patterns via the Brain API.
3. Propose corrections to existing entries when you spot a bug.

Auto-contribution (easiest)

When you accept a generated Blueprint in the Woalz Craft panel:

• The plugin computes a blueprint topology signature (SHA-256 of node types + connections).
• A quality score from objective metrics: connection rate, compile status (clean / warnings / errors), skipped-node count, correction passes.
• If quality >= 0.90, the Blueprint is submitted to POST /contribute/blueprint.
• The Brain runs dedup:
  • Exact signature match in Gold → rejected (already have it).
  • Exact signature match in Candidate → merged (rolling average on quality).
  • Semantic match ≥ 0.85 → rejected (near-duplicate).
  • Otherwise → accepted as Candidate.

Candidates auto-promote to Gold when they accumulate quality ≥ 0.95, query_count ≥ 5, helpful_votes ≥ 3, unhelpful_votes == 0.

Submit a node reference

Node refs tell the AI "this node exists, here's what its pins do". They never appear as Blueprints; they're context.

POST /contribute/node-ref
Authorization: Bearer <write-key>
Content-Type: application/json

{
  "node_name": "CreateActorOfClass",
  "function_target": "",
  "prompt": "Spawn an actor of the given class without a blueprint-level SpawnActor node",
  "category": "Gameplay",
  "pin_data": {
    "inputs": [
      { "name": "ActorClass", "type": "class" },
      { "name": "Transform", "type": "FTransform" }
    ],
    "outputs": [{ "name": "ReturnValue", "type": "Actor*" }]
  },
  "ue5_versions": ["5.5", "5.6", "5.7"],
  "notes": "Prefer this over SpawnActorFromClass when you don't need post-spawn init."
}

Community-tier submissions go to pending and are reviewed by admins. Write-tier submissions are auto-approved.

Submit a pattern

Patterns are text-only guidance: "prefer X over Y" best practices that the AI should internalise.

POST /contribute/pattern
Authorization: Bearer <write-key>

{
  "name": "Use Enhanced Input over legacy InputComponent",
  "prompt": "For any new input handling, use InputAction + InputMappingContext",
  "category": "Input",
  "tags": ["input", "best-practice"],
  "ue5_versions": ["5.1", "5.2", "5.3", "5.4", "5.5", "5.6", "5.7"],
  "notes": "Legacy BindAxis / BindAction are deprecated..."
}

Propose a correction

Spot a broken entry? Suggest a fix via the review queue:

POST /entries/{entry_id}/propose-correction
Authorization: Bearer <any-valid-key>

{
  "diff": {
    "field": "ue5_versions",
    "from": ["5.3", "5.4"],
    "to":   ["5.3", "5.4", "5.5", "5.6", "5.7"],
    "reason": "Also works in 5.5+; verified on my project."
  },
  "reason": "Tested on UE 5.7 and works without changes.",
  "evidence": "Ran compile + PIE on a blank project, clean."
}

Proposals land in /admin/review-queue for admin review. Approved → merged onto the entry; updated_at bumped so plugin caches invalidate.

Rate limits: 20 proposals per proposer per 24h. Duplicate-detection window: 7 days.

What NOT to submit

• Personal / private Blueprints: anything that references your game's proprietary assets, unique mechanics, or NDA content. Keep those in your project.
• Massively generic prompts: "a blueprint" with no specificity has low informational value.
• Broken Blueprints knowingly. Tier-raw is fine for "works with caveats", but outright broken entries get rejected on compile_score.

Credit + GDPR

• contributed_by is normalized on ingest (email → SHA-256 hash, agent labels kept as-is). No raw PII at rest.
• Request erasure via support@woalz.com. Admin can soft-delete (entry stays, authorship cleared) or hard-delete (row + stats removed).

Thanks for helping the Brain grow 🧠✨