Skip to content

TULPA-INTEGRATION-GUIDE.md

Latest commit

 

History

History
380 lines (279 loc) · 9.96 KB

TULPA-INTEGRATION-GUIDE.md

File metadata and controls

380 lines (279 loc) · 9.96 KB

Tulpa System - Quick Integration Guide

Prerequisites

  • The tulpa state has already been added to state.tulpas (line ~8572)
  • Backup your file before making changes
  • Total additions: ~1,050 lines of code

Integration Steps

Step 1: Add CSS Styles (5 minutes)

Location: After line 325 (after .shadow-trait-value style)

Action: Copy the entire "TULPA SYSTEM STYLES" section from tulpa-system-addition.txt (Section 1)

Verification: Search for .tulpa-cursor in your file - it should exist

Step 2: Add HTML UI (3 minutes)

Location: In the sidebar, after other panels (around line 7200, before closing </div> of sidebar)

Action: Copy the HTML UI section from tulpa-system-addition.txt (Section 2)

What to add:

  1. Tulpa Panel (<div class="tulpa-panel" id="tulpaPanel">)
  2. Tulpa Conversation Panel (floating, outside sidebar)

Verification: Search for id="tulpaPanel" - it should exist

Step 3: Add JavaScript (10 minutes)

Location: Before the closing </script> tag (around line 19,000)

Action: Copy the entire TulpaSystem object from tulpa-system-addition.txt (Section 3)

What you're adding:

// ===== TULPA SYSTEM =====
const TulpaSystem = {
    // ~600 lines of code
    init: function() { ... },
    checkUnlock: function() { ... },
    createTulpa: function() { ... },
    // ... many more functions
};

// Initialize on page load
setTimeout(() => TulpaSystem.init(), 1000);

Verification: Search for const TulpaSystem - it should exist

Step 4: Update Export Function (2 minutes)

Location: In the exportData() function (around line 11,869)

Action: Add this line before the final closing brace of the data object:

tulpaSystem: TulpaSystem.getTulpaExportData(),

Context: Add it after the last existing property (probably after paradoxEngine or similar)

Verification: Your export data object should now include tulpa data

Step 5: Update Import Function (2 minutes)

Location: In the importData() function (around line 12,004)

Action: Add tulpa restoration after loading other data:

if (data.tulpaSystem && data.tulpaSystem.tulpas) {
    // Tulpa data will be loaded automatically on next init
    // Just ensure TulpaSystem.init() is called
    setTimeout(() => TulpaSystem.checkUnlock(), 500);
}

Verification: Import function handles tulpa data

Step 6: Call TulpaSystem.checkUnlock() (1 minute)

Location: Find your main animation loop or periodic update function

Action: Add this call to check if tulpas should be unlocked:

// In your main update loop (runs every frame or periodically)
if (state.tulpas.unlocked === false && state.actions.length >= state.tulpas.creationThreshold) {
    TulpaSystem.checkUnlock();
}

Note: This might already be handled by the init() function, but adding it to your update loop ensures it checks regularly.

Testing Your Implementation

Test 1: Basic Functionality

  1. Open the app in a browser
  2. Open developer console (F12)
  3. Check for "🌀 Initializing Tulpa System..." message
  4. Manually trigger unlock for testing:
state.tulpas.unlocked = true;
TulpaSystem.checkUnlock();

Test 2: Create a Tulpa

  1. Ensure tulpa panel is visible
  2. Enter a name: "TestTulpa"
  3. Select personality: "Philosopher"
  4. Click "Create Tulpa"
  5. Verify cursor appears and moves

Test 3: Conversation

  1. Click "Talk" button on tulpa card
  2. Type message: "Hello"
  3. Press Enter
  4. Verify tulpa responds

Test 4: Possession

  1. Wait for possession to trigger (or manually):
const tulpa = state.tulpas.collection[0];
TulpaSystem.triggerPossession(tulpa);
  1. Verify cursor glows and animates

Test 5: Data Persistence

  1. Create a tulpa
  2. Export data
  3. Refresh page
  4. Verify tulpa reappears

Test 6: Multiple Tulpas

  1. Create 3 tulpas with different personalities
  2. Verify each moves differently
  3. Toggle visibility for each
  4. Test conversations with each

Quick Troubleshooting

Issue: Tulpa panel doesn't appear

Solution:

// Force unlock for testing
state.tulpas.unlocked = true;
document.getElementById('tulpaPanel').style.display = 'block';
document.getElementById('tulpaCreationSection').style.display = 'block';
TulpaSystem.renderPersonalityOptions();

Issue: Tulpa cursor not moving

Check:

  1. Is TulpaSystem.updateTulpas() being called in interval?
  2. Is tulpa in state.tulpas.active array?
  3. Does tulpa have a cursor element?

Debug:

console.log('Active tulpas:', state.tulpas.active);
console.log('Tulpa collection:', state.tulpas.collection);
state.tulpas.collection.forEach(t => {
    console.log(t.name, 'has cursor:', !!t.cursor);
});

Issue: Conversation not responding

Check:

console.log('Active conversation:', TulpaSystem.activeTulpaConversation);
console.log('Input element:', document.getElementById('tulpaConversationInput'));

Issue: Export doesn't include tulpas

Check: Ensure TulpaSystem.getTulpaExportData() is called in exportData()

Verify:

const exported = TulpaSystem.getTulpaExportData();
console.log('Tulpa export data:', exported);

Manual Testing Commands

Open browser console and try these:

// 1. Check tulpa state
state.tulpas

// 2. Force unlock
state.tulpas.unlocked = true;
TulpaSystem.checkUnlock();

// 3. Create test tulpa programmatically
document.getElementById('tulpaNameInput').value = 'TestTulpa';
document.querySelector('.tulpa-personality-option').click();
TulpaSystem.createTulpa();

// 4. List all tulpas
state.tulpas.collection.forEach(t => {
    console.log(`${t.name} (${t.personalityType}): Strength ${t.strengthLevel}%, Autonomy ${Math.round(t.autonomy * 100)}%`);
});

// 5. Make tulpa speak
const tulpa = state.tulpas.collection[0];
TulpaSystem.tulpaSpeak(tulpa, "Hello from the tulpa!");

// 6. Trigger possession
TulpaSystem.triggerPossession(state.tulpas.collection[0]);

// 7. Check tulpa movement
setInterval(() => {
    const t = state.tulpas.collection[0];
    console.log(`${t.name} at (${Math.round(t.position.x)}, ${Math.round(t.position.y)})`);
}, 1000);

// 8. Open conversation
TulpaSystem.openConversation(state.tulpas.collection[0].id);

// 9. Fast-forward tulpa strength
state.tulpas.collection[0].strengthLevel = 75;
state.tulpas.collection[0].autonomy = 0.8;
TulpaSystem.renderTulpaList();

// 10. Export and inspect tulpa data
const exportData = TulpaSystem.getTulpaExportData();
console.table(exportData.tulpas);

Performance Notes

  • Tulpa update loop runs at 20 FPS (every 50ms)
  • Max 5 tulpas recommended for performance
  • Trails auto-remove after 1 second
  • Conversation history not capped (consider adding limit for long sessions)
  • UI updates debounced to every 5 seconds

File Locations Reference

Component File Line Range (approx)
State recursive-self-portrait.html 8572-8648
CSS recursive-self-portrait.html 325+ (to add)
HTML recursive-self-portrait.html 7200+ (to add)
JavaScript recursive-self-portrait.html 19000+ (to add)
Export recursive-self-portrait.html 11869 (modify)
Import recursive-self-portrait.html 12004 (modify)

Configuration Options

You can customize these in state.tulpas:

// Unlock threshold (default: 1500)
creationThreshold: 1500,

// Max tulpas (default: 5)
maxTulpas: 5,

// Possession duration (default: 3000ms)
// In tulpa object: possessionDuration: 3000,

// Commentary interval (default: 30000ms)
// In TulpaSystem: commentaryInterval: 30000

// Update frequency (default: 50ms = 20 FPS)
// In setInterval: setInterval(() => this.updateTulpas(), 50)

Customization Ideas

Add New Personality Type

// In state.tulpas.personalityTypes
mystical: {
    name: 'Mystical Seer',
    description: 'Predicts futures through mystical means',
    color: '#ffd700',
    traits: {
        rebelliousness: 0.2,
        curiosity: 0.8,
        wisdom: 0.9,
        playfulness: 0.3,
        aggression: 0.1
    }
}

Then add movement logic in TulpaSystem.updateTulpaMovement().

Adjust Strength Growth Rate

// In TulpaSystem.updateTulpas()
// Change this line:
tulpa.strengthLevel = Math.min(100, tulpa.strengthLevel + 0.1);
// To grow faster:
tulpa.strengthLevel = Math.min(100, tulpa.strengthLevel + 0.5);

Change Possession Frequency

// In TulpaSystem.updateTulpas()
// Change this line:
if (!tulpa.isPossessing && tulpa.strengthLevel > 30 && Math.random() < 0.0002)
// To more frequent (increase probability):
if (!tulpa.isPossessing && tulpa.strengthLevel > 30 && Math.random() < 0.001)

Final Checklist

Before considering integration complete:

  • CSS styles added and no syntax errors
  • HTML UI added to sidebar
  • JavaScript TulpaSystem object added
  • Export function includes tulpa data
  • Import function handles tulpa data
  • TulpaSystem.init() is called
  • No console errors on page load
  • Tulpa panel appears after 1500 actions
  • Can create tulpa successfully
  • Tulpa cursor appears and moves
  • Conversation system works
  • Possession triggers and animates
  • Data persists across refresh
  • Multiple tulpas work simultaneously
  • Export includes tulpa profiles
  • All tests pass

Support

If you encounter issues:

  1. Check browser console for errors
  2. Verify all code sections were added
  3. Ensure no syntax errors (missing brackets, commas)
  4. Test with simple cases first
  5. Use manual testing commands above
  6. Check that viewport element exists: const viewport = document.querySelector('.simulation-viewport');

Good luck with integration! 🌀

The tulpa system adds a fascinating layer of interaction to the Recursive Self-Portrait. Users will be able to create autonomous thoughtforms that truly feel like independent entities born from their behavioral patterns.