Global

Members

# CroquetContext

The react context to store the CroquetReactView instance. You can obtain the value by calling useContext(CroquetContext). You can access useful values such as view, model, etc. from the value of this context.

Example:

const croquetView = useContext(CroquetContext);
const model = croquetView.model;

Methods

# CroquetRoot(sessionParams)

Main wrapper component that starts and manages a croquet session, enabling child elements to use the hooks described below. It takes the same parameters as Session.join except that it doesn't need a root View class, since croquet-react provides a suitable View class behind the scenes.

Parameters:

Name	Type	Description
`sessionParams`	object	The session parameter object that is passed to Session.join.

Returns:

A React component

Example

function CounterApp() {
  return (
    <CroquetRoot
      sessionParams={{
        name: import.meta.env["VITE_CROQUET_NAME"],
        password: import.meta.env["VITE_CROQUET_PASSWORD"],
        appId: import.meta.env["VITE_CROQUET_APP_ID"],
        apiKey: import.meta.env["VITE_CROQUET_API_KEY"],
        model: CounterModel,
      }}
    >
      <p>Your application here</p>
    </CroquetRoot>
  );
}

# useViewId() → {string}

A hook to obtain the viewId.

Returns:

Type: string

Example

const myViewId: string = useViewId();

# useSessionId() → {string}

A hook to obtain the sessionid.

Returns:

Type: string

Example

const sessionId: string = useSessionId();

# useChangeSession() → {function}

This hook returns a function that allows components within the CroquetRoot context to connect to a new session.

Returns:

The returned function accepts a single parameter with the following properties:

name: string - The name of the new session.
password?: string | undefined - (Optional) The password for accessing the new session, if required.

Type: function

Example

// Usage example:
const changeSession = useChangeSession();
changeSession({ name: 'new-session', password: 'password' });

# useConnectedViews() → {object}

This hook returns the views that are connected to the current session.

Returns:

An object containing an array of connected view IDs, and the number of connected views

views: string[] - The array of connected view IDs
viewCount?: number - The number of connected views

Type: object

Example

// Usage example:
const { views, viewCount } = useConnectedViews()

# useReactModelRoot() → {object}

A hook to obtain the root model data. This data comes from a React state, meaning that any change to the model data will cause the components that depend on it to be rerendered.

To use this hook, the application models must inherit from ReactModel

Returns:

An object containing the same properties as the root model object. Additionally, it has one method for each event the model is subscribed to. Calling those methods will broadcast the respective event.

If the model has a property with the same name as one of the events it is subscribed to, the returned object will have the property value.

Type: object

Example

// Any changes to the model will trigger a rerender
const model = useReactModelRoot<RootModel>();

// access model properties
const prop1 = model.property1

// publish an event this model is subscribed to
model.event1()
model.event2(event2Data)

# useModelRoot() → {Model}

A hook to obtain the root model object. Keep in mind that even if the model data changes, React will not rerender the components that depend on it. To achieve this behavior use useReactModelRoot instead.

Returns:

The instance of a subclass of Model used as the root Model.

Type: Model

Example

const model = useModelRoot();

# useModelById(id) → {Model}

A hook to obtain a sub model object.

Parameters:

Name	Type	Description
`id`	number	The id of the model to retrieve

Returns:

The instance of a subclass of Model with the given id.

Type: Model

Example

const submodel = useModelById(rootModel.someData.id);

# usePublish(callback) → {function}

A hook for generating a function that publishes a view event.

The callback function provided takes one argument, data, and returns an array containing three elements that describe the event to be published:

The scope to which the event is being emitted.
The name of the event.
The data attached to the event.

The data argument corresponds to the value passed to the function returned by this hook.

Parameters:

Name	Type	Description
`callback`	function	The callback function used to construct the event data.

Returns:

The function to be used to publish the event.

Type: function

Example

type GrabData = { viewId: string, id: string };

const publishRelease = usePublish<GrabData>(
 (data) => [model.id, 'release', data]
);

// Call the generated function to publish the 'release' event with specific data
publishRelease({ viewId: myViewId, id });

# useSubscribe(scope, eventSpec, callback)

A hook to set up a subscription to a Croquet message.

Parameters:

Name	Type	Description
`scope`	string	The scope in which we are subscribing to the event
`eventSpec`	string	The name of the event we are subscribing to
`callback`	function	The function to be called when the event is received

Example

function grabBall(data:GrabData): void  {
 // Callback logic here
}
useSubscribe<GrabData>(model.id, "grabbed", grabBall);

# useUpdateCallback(callback)

Hook that sets up a callback for Croquet.View.update(). The callback function is called at each simulation cycle.

Parameters:

Name	Type	Description
`callback`	function	The function to be called at each simulation cycle

Example

useUpdateCallback((update_time: number) => console.log(`Updated at ${update_time}!`));

# useSyncedCallback(callback)

Hook that sets up a callback for Croquet.View.synced(). The callback function is called when a Croquet synced event occurs.

Parameters:

Name	Type	Description
`callback`	function	The function to be called when a `synced` event occurs

Example

function onSynced(): void  {
 // Callback logic here
}
useSyncedCallback(onSynced);

# useDetachCallback(callback)

Hook that sets up a callback for Croquet.View.detach(). The callback function is called when the root View is detached.

Parameters:

Name	Type	Description
`callback`	function	The function to be called when the root View is detached

Example

function onDetached(): void  {
 // Callback logic here
}
useDetachCallback(onDetached);

# InCroquetSession()

Main wrapper component that starts and manages a croquet session, enabling child elements to use the hooks described above. It takes the same parameters as Session.join except that it doesn't need a root View class, since croquet-react provides a suitable View class behind the scenes.

Deprecated:: Use CroquetRoot instead.

Example

function MyApp() {
   return (
     <InCroquetSession
       apiKey="1_123abc",
       appId="com.example.myapp"
       name="mySession"
       password="secret"
       model={MyRootModel}
        ...
     >
       // child elements that use hooks go here...
       <MyComponent/>
     </InCroquetSession>
   );
}

# createCroquetSession()

When Croquet is used in a component that is a part of a bigger application, it is sometimes better to establish the Croquet session instance outside,and then pass it in to the Croquet-powered part.

Deprecated:: Use CroquetRoot instead.

Returns:

the Croquet session object.

Example

const [croquetSession, setCroquetSession] = useState(null);
const calledOnce = useRef(false);
useEffect(() => {
  if (!calledOnce.current) {
    calledOnce.current = true;
    const sessionParams = {
      name: projectId,
      apiKey: import.meta.env.VITE_CROQUET_API_KEY,
      tps: 0.5,
      appId: import.meta.env.VITE_CROQUET_APP_ID,
      password: "abc",
      model: MyCroquetModel,
      eventRateLimit: import.meta.env.EVENT_RATE_LIMIT || 60,
    };
    createCroquetSession(sessionParams as any).then((session) => {
      console.log(`session created`);
      setCroquetSession(session);
    });
  }
}, [...]);
return (
  <CroquetRoot session={croquetSession}>
    <MyCroquetComponent/>
  </CroquetRoot>
);