Document manual model update (#54)

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## [[unpublished]](https://github.com/mlange-42/arche-model/compare/v0.6.0...main)
+## [[v0.7.0]](https://github.com/mlange-42/arche-model/compare/v0.6.0...v0.7.0)
 
 ### Features
 

model/model.go

@@ -65,11 +65,15 @@ func (m *Model) Seed(seed ...uint64) *Model {
 	return m
 }
 
-// Run the model. Initializes the model if it is not already initialized.
+// Run the model, updating systems and ui systems according to Model.TPS and Model.FPS, respectively.
+// Initializes the model if it is not already initialized.
 // Finalizes the model after the run.
 //
 // Runs until Terminate in the resource resource.Termination is set to true
 // (see [resource.Termination]).
+//
+// To perform updates manually, see [Model.Update] and [Model.UpdateUI],
+// as well as [Model.Initialize] and [Model.Finalize].
 func (m *Model) Run() {
 	m.Systems.run()
 }
@@ -82,16 +86,20 @@ func (m *Model) Initialize() {
 // Update the model's systems.
 // Return whether the run should continue.
 //
+// Ignores Model.TPS.
+//
 // Panics if [Model.Initialize] was not called.
 func (m *Model) Update() bool {
-	return m.Systems.UpdateSystems()
+	return m.Systems.updateSystems()
 }
 
 // UpdateUI the model's UI systems.
 //
+// Ignores Model.FPS.
+//
 // Panics if [Model.Initialize] was not called.
 func (m *Model) UpdateUI() {
-	m.Systems.UpdateUISystems()
+	m.Systems.updateUISystems()
 }
 
 // Finalize the model.

model/model_test.go

@@ -82,6 +82,24 @@ func ExampleModel() {
 	// Output:
 }
 
+func ExampleModel_manualUpdate() {
+	// Create a new, seeded model.
+	m := model.New().Seed(123)
+
+	// Add systems.
+	m.AddSystem(&system.FixedTermination{
+		Steps: 100,
+	})
+
+	// Run the simulation manually.
+	m.Initialize()
+	for m.Update() {
+		m.UpdateUI()
+	}
+	m.Finalize()
+	// Output:
+}
+
 func ExampleModel_Reset() {
 	// Create a new model.
 	m := model.New()

model/systems.go

@@ -213,8 +213,8 @@ func (s *Systems) initialize() {
 // Update all systems.
 func (s *Systems) update() bool {
 	s.locked = true
-	update := s.updateSystems()
-	s.updateUISystems(update)
+	update := s.updateSystemsTimed()
+	s.updateUISystemsTimed(update)
 	s.locked = false
 
 	s.removeSystems()
@@ -229,8 +229,8 @@ func (s *Systems) update() bool {
 	return !s.termRes.Get().Terminate
 }
 
-// UpdateSystems updates all normal systems
-func (s *Systems) UpdateSystems() bool {
+// updateSystems updates all normal systems
+func (s *Systems) updateSystems() bool {
 	if !s.initialized {
 		panic("the model is not initialized")
 	}
@@ -251,8 +251,8 @@ func (s *Systems) UpdateSystems() bool {
 	return !s.termRes.Get().Terminate
 }
 
-// UpdateUISystems updates all UI systems
-func (s *Systems) UpdateUISystems() {
+// updateUISystems updates all UI systems
+func (s *Systems) updateUISystems() {
 	if !s.initialized {
 		panic("the model is not initialized")
 	}
@@ -280,7 +280,15 @@ func (s *Systems) wait() {
 }
 
 // Update normal systems.
-func (s *Systems) updateSystems() bool {
+func (s *Systems) updateSystemsSimple() bool {
+	for _, sys := range s.systems {
+		sys.Update(s.world)
+	}
+	return true
+}
+
+// Update normal systems.
+func (s *Systems) updateSystemsTimed() bool {
 	update := false
 	if s.Paused {
 		update = !time.Now().Before(s.nextUpdate)
@@ -303,14 +311,6 @@ func (s *Systems) updateSystems() bool {
 	return update
 }
 
-// Update normal systems.
-func (s *Systems) updateSystemsSimple() bool {
-	for _, sys := range s.systems {
-		sys.Update(s.world)
-	}
-	return true
-}
-
 // Update ui systems.
 func (s *Systems) updateUISystemsSimple() {
 	for _, sys := range s.uiSystems {
@@ -322,7 +322,7 @@ func (s *Systems) updateUISystemsSimple() {
 }
 
 // Update UI systems.
-func (s *Systems) updateUISystems(updated bool) {
+func (s *Systems) updateUISystemsTimed(updated bool) {
 	if !s.Paused && s.FPS <= 0 {
 		if updated {
 			s.updateUISystemsSimple()