Merge pull request #749 from JiepengTan/pr_update_spx_api

Update spx api

Author: JiepengTan

internal/engine/coro.go

@@ -19,6 +19,10 @@ func GetGame() any {
 	return pgame
 }
 
+func IsSpxEnv() bool {
+	return GetGame() != nil
+}
+
 func SetCoroutines(co *coroutine.Coroutines) {
 	gco = co
 	profiler.SetGco(co)

pkg/api/coro.go pkg/spx/api.gopkg/api/coro.go renamed to pkg/spx/api.go

@@ -1,15 +1,46 @@
-package api
+package spx
 
 import (
+	"sync/atomic"
+	"time"
+
 	"github.com/goplus/spx/v2/internal/engine"
 )
 
 // HasInit checks if the SPX engine has been initialized.
-func HasInit() bool {
-	return engine.GetGame() != nil
+func IsSpxEnv() bool {
+	return engine.IsSpxEnv()
+}
+
+// Executes the given function in a native Go goroutine from the current SPX coroutine context and waits for completion.
+// While waiting, it yields control via waitNextFrame to avoid blocking the SPX main thread.
+// Use this when you need to run potentially blocking Go operations (e.g., network requests, file I/O) from within SPX.
+func RunGoFromSpx(fn func()) {
+	done := &atomic.Bool{}
+	// Run the actual logic in a go routine to avoid blocking
+	go func() {
+		defer done.Store(true)
+		fn()
+	}()
+	// Wait for completion while yielding control to SPX
+	for !done.Load() {
+		WaitNextFrame()
+	}
+}
+
+// Executes the given function in an SPX coroutine from the current Go goroutine context and waits for completion.
+// This function blocks until fn finishes execution.
+// Use this when you need to synchronously wait for the SPX coroutine to complete.
+func RunSpxFromGo(fn func()) {
+	done := make(chan struct{}, 1)
+	StartSpxCoro(func() {
+		defer close(done)
+		fn()
+	})
+	<-done
 }
 
-// Go starts a new spx coroutine that executes the given function concurrently.
+// Starts a new spx coroutine that executes the given function concurrently.
 // This is useful for running multiple operations in parallel without blocking
 // the main execution flow.
 //
@@ -25,24 +56,28 @@ func HasInit() bool {
 //
 //	done := false
 //	// ... do something
-//	api.Go(func() {
+//	spx.GoAsync(func() {
 //	    // ... do something
 //	    for !done {
 //	        // Do some work here
-//	        api.WaitNextFrame() // CRITICAL: Yield control to prevent freezing
+//	        spx.WaitNextFrame() // CRITICAL: Yield control to prevent freezing
 //	    }
 //	})
 //
 // Example of simple delayed execution:
 //
-//	api.Go(func() {
-//	    api.Wait(2.0)
+//	spx.GoAsync(func() {
+//	    spx.Wait(2.0)
 //	    fmt.Println("Hello after 2 seconds")
 //	})
-func Go(fn func()) {
-	engine.Go(engine.GetGame(), func() {
-		fn()
-	})
+func StartSpxCoro(fn func()) {
+	if IsSpxEnv() {
+		engine.Go(engine.GetGame(), func() {
+			fn()
+		})
+	} else {
+		go fn()
+	}
 }
 
 // Wait pauses the current coroutine for the specified number of seconds.
@@ -62,9 +97,16 @@ func Go(fn func()) {
 //
 // Example:
 //
-//	actualTime := api.Wait(1.5) // Wait for 1.5 seconds
+//	actualTime := spx.Wait(1.5) // Wait for 1.5 seconds
 func Wait(secs float64) float64 {
-	return engine.Wait(secs)
+	if IsSpxEnv() {
+		return engine.Wait(secs)
+	} else {
+		// Fallback to a regular wait
+		startTime := time.Now()
+		time.Sleep(time.Duration(secs * float64(time.Second)))
+		return time.Since(startTime).Seconds()
+	}
 }
 
 // WaitNextFrame pauses the current coroutine until the next frame is rendered.
@@ -83,9 +125,16 @@ func Wait(secs float64) float64 {
 //	for i := 0; i < 1000; i++ {
 //	    // Do some expensive work
 //	    if i%100 == 0 {
-//	        api.WaitNextFrame() // Yield control every 100 iterations
+//	        spx.WaitNextFrame() // Yield control every 100 iterations
 //	    }
 //	}
 func WaitNextFrame() float64 {
-	return engine.WaitNextFrame()
+	if IsSpxEnv() {
+		return engine.WaitNextFrame()
+	} else {
+		// Fallback to a regular wait
+		startTime := time.Now()
+		time.Sleep(time.Millisecond * 16) // Approx 60 FPS
+		return time.Since(startTime).Seconds()
+	}
 }