AeThex-Labs/AeThex-Engine-Core

Fork 0

MrPiglr 73b27e6fbe

new file: LOGO_CONFIG_GUIDE.md

2026-02-24 04:30:27 +00:00

18 KiB

Raw Blame History

Migrating from Godot to AeThex

Complete guide for porting existing Godot projects to AeThex Engine.

Overview

AeThex is built on Godot 4.3-stable, so most Godot projects work with zero changes. This guide covers:

Compatibility guarantees
AeThex-specific features
Breaking changes (if any)
Migration steps
Optimization tips

Compatibility

✅ Fully Compatible (No Changes Needed)

Scene System:

.tscn files work identically
Scene inheritance works
Resources (.tres) work
Shaders (.gdshader) work

Scripting:

GDScript syntax unchanged
C# works (if mono module built)
GDExtension works
Signal system identical

Assets:

Images (.png, .jpg, .svg)
3D models (.gltf, .glb, .obj, .fbx)
Audio (.wav, .ogg, .mp3)
Fonts (.ttf, .otf)

Core Features:

Rendering (2D/3D)
Physics (2D/3D)
Audio system
Input handling
Animation system
UI system

⚠️ Minor Differences

Binary Name:

Godot: godot or godot.exe
AeThex: aethex or aethex.exe
Impact: Update launch scripts if any

Project Settings:

Project file: project.godot (unchanged)
Config section: [application] (unchanged)
Impact: None, uses same format

Export Templates:

Must use AeThex export templates
Available in Editor → Export → Manage Templates
Impact: Re-export for production

❌ Not Supported (Yet)

Platform-Specific:

Console exports (PS5, Xbox, Switch)
- Coming in AeThex 2.0
Native iOS export
- Use web export for now

What's Different in AeThex?

1. Built-in Cloud Services

New Global Singletons:

# Godot: Must integrate third-party services
# AeThex: Built-in!

AeThexCloud.connect_to_cloud()
AeThexAuth.login_email("user@example.com", "pass")
AeThexSaves.save_game("slot1", save_data)
AeThexMultiplayer.create_room("room-123")
AeThexAnalytics.track_event("level_complete", {})
AeThexAI.ask_assistant("How do I add jumping?")

Impact: Optional feature, only use if needed.

2. Studio IDE Integration

Live Reload:

# Automatically reloads when files change in Studio IDE
# No need to manually refresh

Remote Debugging:

# Connect Studio IDE to running game
AeThexStudio.connect_debugger()

Impact: Optional, works with standard Godot workflow too.

3. Enhanced Multiplayer

Simplified API:

# Godot: Complex setup with MultiplayerPeer, etc.
var peer = ENetMultiplayerPeer.new()
peer.create_server(7000)
multiplayer.multiplayer_peer = peer

# AeThex: One line!
AeThexMultiplayer.create_room("my-room")

Impact: Use if you want easy multiplayer. Godot's multiplayer still works.

4. AI Assistant

Code Generation:

# Ask AI for help directly in code
var code = await AeThexAI.generate_code("Create a jump function for player")
print(code)

Impact: Completely optional feature.

Migration Steps

Option 1: Quick Test (5 minutes)

Test if your Godot project works in AeThex without changes.

# 1. Download AeThex
wget https://aethex.io/download/aethex-linux.tar.gz
tar -xzf aethex-linux.tar.gz

# 2. Open your Godot project
./aethex --editor --path /path/to/your/godot/project

# 3. Hit Play (F5)
# If it works, you're done! 🎉

What to check:

✅ Scene loads correctly
✅ Scripts run without errors
✅ Physics/collisions work
✅ UI displays correctly
✅ Audio plays

Common issues:

Missing export templates → Download from Editor → Manage Templates
Custom GDExtension → Rebuild for AeThex (API compatible)
Platform-specific code → May need adjustments

Option 2: Full Migration (30 minutes)

Properly migrate and add AeThex features.

Step 1: Backup Your Project

# Create a copy
cp -r my-godot-project my-aethex-project
cd my-aethex-project

Step 2: Open in AeThex

aethex --editor --path .

Step 3: Update Project Settings

Optional: Add AeThex branding

Editor → Project Settings → Application:

Change icon to your AeThex-branded icon
Update splash screen
Update app name

Step 4: Test All Features

Create a test checklist:

[ ] Main menu loads
[ ] Gameplay works
[ ] Save/load works
[ ] Settings apply
[ ] All levels playable
[ ] Audio works
[ ] Inputs respond
[ ] Export works

Step 5: Add Cloud Features (Optional)

Authentication:

# In main menu
extends Control

func _ready():
    if not AeThexAuth.is_logged_in():
        show_login_dialog()

func show_login_dialog():
    $LoginDialog.show()

func _on_login_pressed():
    var email = $EmailField.text
    var password = $PasswordField.text
    
    var result = await AeThexAuth.login_email(email, password)
    if result.success:
        get_tree().change_scene_to_file("res://main_game.tscn")

Cloud Saves:

# Replace local save/load with cloud

# OLD (Godot):
func save_game():
    var save_file = FileAccess.open("user://save.dat", FileAccess.WRITE)
    save_file.store_var(save_data)
    save_file.close()

# NEW (AeThex):
func save_game():
    await AeThexSaves.save_game("save_slot_1", save_data)
    # Data automatically syncs to cloud!

Multiplayer:

# OLD (Godot): Complex setup
var peer = ENetMultiplayerPeer.new()
peer.create_server(7000, 4)
multiplayer.multiplayer_peer = peer

# NEW (AeThex): Simple
AeThexMultiplayer.create_room("my-game-room")

Step 6: Test Cloud Features

Test cloud saves:

Save game
Close game
Open on different device
Load game
Verify data synced

Test multiplayer:

Run game twice
Create room in first instance
Join room in second instance
Verify players see each other

Step 7: Export

Generate export templates:

# In editor
Editor → Manage Export Templates → Download and Install

Export platforms:

Windows (x86_64)
Linux (x86_64)
macOS (universal)
Web (HTML5)
Android (APK/AAB)

API Mapping

Multiplayer Comparison

Godot Built-in:

# Server setup
var peer = ENetMultiplayerPeer.new()
peer.create_server(7000, 4)
multiplayer.multiplayer_peer = peer

# Client connect
var peer = ENetMultiplayerPeer.new()
peer.create_client("192.168.1.100", 7000)
multiplayer.multiplayer_peer = peer

# RPC
@rpc("any_peer", "reliable")
func take_damage(amount: int):
    health -= amount

# Call RPC
rpc("take_damage", 10)

AeThex Cloud:

# Create room (auto server/client)
AeThexMultiplayer.create_room("room-123")

# Join room
AeThexMultiplayer.join_room("room-123")

# RPC (same API)
@rpc("any_peer", "reliable")
func take_damage(amount: int):
    health -= amount

# Call RPC (same)
rpc("take_damage", 10)

# OR use AeThex helper
AeThexMultiplayer.call_rpc("take_damage", [10])

Benefits of AeThex:

No port forwarding needed
No NAT traversal issues
Room codes for easy joining
Works across internet automatically

Save System Comparison

Godot Built-in:

func save_game():
    var save_file = FileAccess.open("user://save.dat", FileAccess.WRITE)
    var save_data = {
        "health": player.health,
        "position": player.position,
        "inventory": player.inventory
    }
    save_file.store_var(save_data)
    save_file.close()

func load_game():
    if not FileAccess.file_exists("user://save.dat"):
        return
    
    var save_file = FileAccess.open("user://save.dat", FileAccess.READ)
    var save_data = save_file.get_var()
    save_file.close()
    
    player.health = save_data.health
    player.position = save_data.position
    player.inventory = save_data.inventory

AeThex Cloud:

func save_game():
    var save_data = {
        "health": player.health,
        "position": player.position,
        "inventory": player.inventory
    }
    
    await AeThexSaves.save_game("slot1", save_data)
    # Automatically compressed, checksummed, uploaded!

func load_game():
    var save_data = await AeThexSaves.load_game("slot1")
    
    if save_data:
        player.health = save_data.health
        player.position = save_data.position
        player.inventory = save_data.inventory

Benefits of AeThex:

Cross-device sync
Cloud backup
Version history
Conflict resolution
Automatic compression

Breaking Changes

Changes from Godot 4.3

None! AeThex maintains full Godot 4.3 compatibility.

Future Breaking Changes (AeThex 2.0)

Planned for 6+ months from now:

May deprecate some Godot built-in networking in favor of AeThex Cloud
Will provide migration tools
Will maintain backwards compatibility mode

Migration path will be provided before any breaking changes.

Performance Considerations

AeThex Overhead

Engine size:

Godot 4.3: ~40MB
AeThex: ~45MB (+5MB for cloud modules)

Memory overhead:

+10-20MB for cloud SDK
+5MB for AI module
Only when features are used

Runtime performance:

Zero overhead if cloud features not used
<1ms per frame for cloud sync
Async operations don't block game thread

Optimization Tips

1. Lazy Load Cloud Features

# Don't connect immediately
func _ready():
    pass  # Cloud not connected yet

# Connect when needed
func on_login_button_pressed():
    await AeThexCloud.connect_to_cloud()
    # Now can use cloud features

2. Batch Analytics Events

# Bad: Send every frame
func _process(delta):
    AeThexAnalytics.track_event("player_moved", {})

# Good: Batch every 10 seconds
var analytics_buffer = []

func _process(delta):
    analytics_buffer.append("player_moved")

func _on_analytics_timer_timeout():  # Every 10 seconds
    if analytics_buffer.size() > 0:
        AeThexAnalytics.track_event("player_actions", {
            "count": analytics_buffer.size()
        })
        analytics_buffer.clear()

3. Use Auto-Sync for Saves

# Let AeThex handle save timing
func _ready():
    AeThexSaves.enable_auto_sync(true)
    # Saves sync in background at optimal times

Common Migration Issues

Issue 1: Export Templates Not Found

Error: "No export templates found"

Solution:

# In editor
Editor → Manage Export Templates → Download and Install

# OR manually
mkdir -p ~/.local/share/aethex/export_templates/4.3.stable
cp -r aethex_templates/* ~/.local/share/aethex/export_templates/4.3.stable/

Issue 2: GDExtension Doesn't Load

Error: "GDExtension failed to load"

Cause: GDExtension compiled for Godot, not AeThex

Solution: Rebuild GDExtension:

# In your GDExtension project
scons platform=linux custom_api_file=/path/to/aethex/extension_api.json

# Copy to your AeThex project
cp bin/libmyextension.so /path/to/project/addons/myextension/

Issue 3: Multiplayer Not Connecting

Error: "Failed to create room"

Causes:

Not connected to internet
Firewall blocking
Cloud service down

Solution:

# Check connection first
func start_multiplayer():
    if not AeThexCloud.is_connected():
        var result = await AeThexCloud.connect_to_cloud()
        if not result.success:
            show_error("Cannot connect to cloud services")
            return
    
    # Now try multiplayer
    if not AeThexMultiplayer.create_room("my-room"):
        show_error("Failed to create room")

Issue 4: Cloud Saves Not Working

Error: "Save failed: Not authenticated"

Cause: User not logged in

Solution:

# Require login or use guest mode
func _ready():
    if not AeThexAuth.is_logged_in():
        # Option 1: Login as guest (anonymous)
        await AeThexAuth.login_as_guest()
        
        # Option 2: Show login screen
        # show_login_screen()

# Now saves will work
func save_game():
    await AeThexSaves.save_game("slot1", data)

Issue 5: Android Export Fails

Error: "Failed to export for Android"

Cause: Missing Android SDK or keystore

Solution:

# 1. Install Android SDK
# Editor → Editor Settings → Export → Android → Android SDK Path

# 2. Create debug keystore
keytool -genkey -v -keystore debug.keystore -alias androiddebugkey \
  -keyalg RSA -keysize 2048 -validity 10000 -storepass android

# 3. Configure in export preset
# Project → Export → Android → Keystore

Feature Parity Checklist

Use this to verify your migrated project:

Core Features

[ ] Scenes load correctly
[ ] Scripts execute without errors
[ ] Physics works (collisions, rigidbodies)
[ ] Input responds (keyboard, mouse, gamepad)
[ ] Audio plays (music, sound effects)
[ ] UI displays correctly (buttons, labels)
[ ] Animations play
[ ] Shaders render correctly
[ ] Particles work
[ ] Save/load works

AeThex Features (if using)

[ ] Can connect to cloud
[ ] Authentication works
[ ] Cloud saves sync
[ ] Multiplayer connects
[ ] Analytics tracks events
[ ] AI assistant responds
[ ] Studio IDE connects

Export Targets

[ ] Windows build works
[ ] Linux build works
[ ] macOS build works
[ ] Web export works
[ ] Android APK installs

Best Practices

1. Gradual Migration

Don't convert everything at once:

Phase 1: Test compatibility

Open project in AeThex
Run all scenes
Test all gameplay
Verify exports work

Phase 2: Add authentication (optional)

Implement login screen
Use guest mode for testing
Add account management

Phase 3: Convert saves (optional)

Migrate local saves to cloud
Add auto-sync
Test cross-device sync

Phase 4: Add multiplayer (optional)

Replace custom networking with AeThex
Test room creation/joining
Verify state sync

2. Fallback to Local

Always support offline mode:

func save_game():
    # Try cloud first
    if AeThexCloud.is_connected():
        var result = await AeThexSaves.save_game("slot1", data)
        if result.success:
            return
    
    # Fallback to local
    save_local(data)

func save_local(data):
    var file = FileAccess.open("user://save.dat", FileAccess.WRITE)
    file.store_var(data)
    file.close()

3. Graceful Degradation

Handle cloud service failures:

func _ready():
    # Try to connect
    var result = await AeThexCloud.connect_to_cloud()
    
    if result.success:
        # Cloud features available
        $MultiplayerButton.disabled = false
        $CloudSaveIndicator.show()
    else:
        # Offline mode
        $MultiplayerButton.disabled = true
        $CloudSaveIndicator.hide()
        show_notification("Playing in offline mode")

4. Version Control

Keep Godot project for reference:

# Branch strategy
git checkout -b aethex-migration
# Make changes in this branch
# Keep main branch as Godot version

Case Studies

Case Study 1: "Platformer Game"

Original: Godot 4.2 project, single-player, local saves

Migration time: 10 minutes

Changes:

None required for basic functionality
Added cloud saves (5 min)
Added leaderboard (5 min)

Result: Works perfectly, no issues

Case Study 2: "Multiplayer Shooter"

Original: Godot 4.3, custom ENet networking, 500+ lines of networking code

Migration time: 2 hours

Changes:

Replaced ENet with AeThexMultiplayer
Removed 500 lines of networking code
Added matchmaking UI
Tested multiplayer thoroughly

Result: Simpler codebase, easier to maintain, works across internet without port forwarding

Case Study 3: "RPG with Custom GDExtension"

Original: Godot 4.3, custom C++ extension for save encryption

Migration time: 1 hour

Changes:

Rebuilt GDExtension for AeThex
Replaced custom encryption with AeThex cloud saves (has built-in encryption)
Removed 200+ lines of C++ code

Result: Less code, more secure, cross-device sync

FAQ

Q: Will my Godot 3.x project work?

A: No direct compatibility. Godot 4.x made breaking changes from 3.x. Follow the official Godot 3→4 migration guide first, then migrate to AeThex.

Q: Can I use Godot plugins/addons?

A: Yes! Most Godot 4.x plugins work in AeThex without changes.

Q: Will AeThex stay compatible with Godot?

A: Yes, we track Godot stable releases and maintain compatibility. Major changes will be communicated in advance.

Q: Can I export to the same platforms as Godot?

A: Yes for: Windows, Linux, macOS, Web, Android. No (yet) for: iOS native, consoles.

Q: Do I have to use cloud features?

A: No! They're completely optional. AeThex works as a standard Godot engine if you don't use cloud features.

Q: What happens if AeThex cloud services go down?

A: Implement fallbacks (see Best Practices). Your game should work offline with local saves/single-player.

Q: Can I self-host the cloud services?

A: Yes! The cloud services are open-source. See Self-Hosting Guide (coming soon).

Q: Does AeThex collect any data?

A: Only if you use analytics features. See Privacy Policy.

Getting Help

Documentation:

API Reference - Complete API docs
Tutorials - Step-by-step guides
Architecture Overview - System design

Community:

Discord - Real-time chat
Forum - Discussions
GitHub Issues - Bug reports

Support:

Email Support - Response within 24h
Pro Support - Priority support for paying customers

Next Steps

Try it: Open your Godot project in AeThex and hit Play
Test: Verify all features work
Enhance: Add cloud features gradually
Deploy: Export and ship!

Ready to start? Head to Getting Started!

18 KiB Raw Blame History

Migrating from Godot to AeThex

Overview

Compatibility

✅ Fully Compatible (No Changes Needed)

⚠️ Minor Differences

❌ Not Supported (Yet)

What's Different in AeThex?

1. Built-in Cloud Services

2. Studio IDE Integration

3. Enhanced Multiplayer

4. AI Assistant

Migration Steps

Option 1: Quick Test (5 minutes)

Option 2: Full Migration (30 minutes)

Step 1: Backup Your Project

Step 2: Open in AeThex

Step 3: Update Project Settings

Step 4: Test All Features

Step 5: Add Cloud Features (Optional)

Step 6: Test Cloud Features

Step 7: Export

API Mapping

Multiplayer Comparison

Save System Comparison

Breaking Changes

Changes from Godot 4.3

Future Breaking Changes (AeThex 2.0)

Performance Considerations

AeThex Overhead

Optimization Tips

Common Migration Issues

Issue 1: Export Templates Not Found

Issue 2: GDExtension Doesn't Load

Issue 3: Multiplayer Not Connecting

Issue 4: Cloud Saves Not Working

Issue 5: Android Export Fails

Feature Parity Checklist

Core Features

AeThex Features (if using)

Export Targets

Best Practices

1. Gradual Migration

2. Fallback to Local

3. Graceful Degradation

4. Version Control

Case Studies

Case Study 1: "Platformer Game"

Case Study 2: "Multiplayer Shooter"

Case Study 3: "RPG with Custom GDExtension"

FAQ

Q: Will my Godot 3.x project work?

Q: Can I use Godot plugins/addons?

Q: Will AeThex stay compatible with Godot?

Q: Can I export to the same platforms as Godot?

Q: Do I have to use cloud features?

Q: What happens if AeThex cloud services go down?

Q: Can I self-host the cloud services?

Q: Does AeThex collect any data?

Getting Help

Next Steps

18 KiB

Raw Blame History