[docs] Confusing state names in basic light switch example

[wujekbogdan]

Hey,

Let me start by saying that I'm super impressed with LogicBlocks - the quality of the lib, the design, and the amazing docs you provide. I wish other libraries had such good official support.

Let me also emphasize that neither game dev nor C# are my specialty. I'm a software dev, but at the same time I'm a Godot/C# newbie, so my insights might not apply to regular lib users - it's just a noob perspective.

Anyway, I was going through the LogicBlocks Basics docs and got puzzled by one thing that I think could be improved.

The confusing part

Here's the snipped from the States docs:

public abstract record State : StateLogic<State> {
  public record PoweredOn : State, IGet<Input.Toggle> {}
 
  public record PoweredOff : State, IGet<Input.Toggle> {
    public Transition On(in Input.Toggle input) => To<PoweredOn>();
  }
}

I know it's silly, but there's a confusing coincidence here. The method name is On while states are named PoweredOn and PoweredOff. The fact that it's named On has absolutely nothing to do with the On/Off states, but someone (like me ;P) might think these things are somehow related.

The brain naturally connects "PoweredOff state has an On() method that goes to PoweredOn" - it feels like the method name is semantically related to the state names, when it's actually just coincidental.

Of course, if you spend a moment exploring the lib's interfaces, you'll figure out it's just the way to define input handlers (On input do something), but at first glance, instinct guides you in the wrong direction.

Suggested solutions

An obvious way to solve it would be just a state rename: e.g. Active / Inactive or SwitchUp / SwitchDown:

public abstract record State : StateLogic<State> {
   public record SwitchUp : State, IGet<Input.Toggle> {}

   public record SwitchDown : State, IGet<Input.Toggle> {
     public Transition On(in Input.Toggle input) => To<SwitchUp>();
   }
 }

What could also help is introducing multiple input handlers, so that we have more than one On method call. This would require a bit more work since the light switch doesn't have many states it can transition between ;), so I guess it would require the whole example to be turned into something else - e.g. a character that is idle, running, or walking. But tbh I think that renaming states is good enough.

And yes - I know that multiple handlers are introduced later in the docs which clarify things, but if you read the docs the way I do - proceeding only after you've digested the information so far - you get confused before you reach the part that clarifies the confusion.

[jolexxa]

Hey, glad you are enjoying the library! I'm slowly chugging away at LogicBlocks 6 in between projects, which is more or less a soft-rewrite with a number of API changes. I hear what you're saying and I'll keep this in mind while redesigning API's. In the meantime, we could use a more involved example to show how it works, such as a toaster or something. But I guess that's more of a documentation issue that can be fixed over at https://github.com/chickensoft-games/chickensoft_site