new-component

# Adding a new component

Components in gz-sim are header-only wrappers around the `Component<>`
template. They live in `include/gz/sim/components/<Name>.hh`.

## Decide first

1. **What's the data type?** A plain struct, a `math::Vector3d`, an
   `std::string`, a `msgs::*`?  Components don't have to be POD but they
   must be copyable.
2. **Does it need serialization?** If users should be able to log/replay
   the component or read it from SDF, you need to give it a
   `Serializer<T>` and register it with `ComponentFactory`.
3. **Is there a Cmd / Reset variant?** If this component represents
   physical state that physics writes, you probably also want
   `<Name>Cmd.hh` (user → physics) and `<Name>Reset.hh` (snapshot for
   `Reset()`).

## Template (no custom serializer)

```cpp
// include/gz/sim/components/Foo.hh
#ifndef GZ_SIM_COMPONENTS_FOO_HH_
#define GZ_SIM_COMPONENTS_FOO_HH_

#include <gz/sim/components/Component.hh>
#include <gz/sim/components/Factory.hh>
#include <gz/sim/config.hh>

namespace gz::sim
{
inline namespace GZ_SIM_VERSION_NAMESPACE {
namespace components
{
  /// \brief One-line description of what this component represents and
  ///        which entities it gets attached to.
  using Foo = Component<double, class FooTag>;
  GZ_SIM_REGISTER_COMPONENT("gz_sim_components.Foo", Foo)
}
}
}

#endif
```

Key points:

* The unique tag `class FooTag` is what prevents two components with the
  same data type from collapsing into one — never skip it.
* `GZ_SIM_REGISTER_COMPONENT(name, type)` is required for *any* component
  that needs to round-trip through `ComponentFactory`.

## Template (custom data type + serializer)

```cpp
#ifndef GZ_SIM_COMPONENTS_BAR_HH_
#define GZ_SIM_COMPONENTS_BAR_HH_

#include <gz/msgs/double.pb.h>
#include <gz/sim/components/Component.hh>
#include <gz/sim/components/Factory.hh>
#include <gz/sim/components/Serialization.hh>
#include <gz/sim/config.hh>

namespace gz::sim
{
inline namespace GZ_SIM_VERSION_NAMESPACE {
namespace components
{
  using BarSerializer = serializers::MsgsDoubleSerializer;
  using Bar = Component<msgs::Double, class BarTag, BarSerializer>;
  GZ_SIM_REGISTER_COMPONENT("gz_sim_components.Bar", Bar)
}
}
}

#endif
```

For brand-new data types, define `Serializer<T>` with
`static std::ostream &Serialize(...)` and
`static std::istream &Deserialize(...)` in
`include/gz/sim/components/Serialization.hh` style and reference it from
the component.

## CMake plumbing

Add the new header to
`include/gz/sim/components/CMakeLists.txt` so it gets installed:

```cmake
set (component_headers
  Actor.hh
  ...
  Foo.hh        # <-- new
  ...
)
```

Headers are picked up automatically by the install logic — just keep the
list alphabetical to match existing style.

## Tests

* Add a small `Foo_TEST.cc` next to the existing component tests under
  `src/components/` if there's non-trivial behaviour (e.g. operator==
  or a custom serializer). Trivial typedef components don't need a
  dedicated test.
* If the component is logged/replayed, add a round-trip test under
  `test/integration/log_system.cc` patterns.

## Migration note

If the component is part of the public API, append a one-line entry to
`Migration.md` under the next-release section so downstream users notice.

## Common mistakes

* Reusing an existing tag class — two components with the same tag are
  the *same* component.
* Forgetting the `GZ_SIM_REGISTER_COMPONENT` macro for a serialized type.
* Adding mutation logic into the component header — components are *data*,
  behaviour belongs in a system.