Guide How L2Acp Works And How To Contribute

[Elfo]

How does it work and how to contribute

 

First and foremost let me make something clear.

 

This is a project under GPLv2. ANY changes or modifications you make to the software need to be made public under the same license for everyone to see.

 

The main reason i made this opensource is so people can jump in and help out in exchange of using it for free.

 

An example would be the follow: If you adapt the code for l2j high five, you MUST by law make it public.

Any violations will be reported and offenders will need to deal with the legal issues.

 

 

Now that i have that out of the way let me talk you through the workflow.

 

This is what a full request from the user looks like

1. The user does an action on the site.
2. The request is send to the website and it is being validated for authenticity.
3. If it is valid then the website is sending an encrypted request to the server api.
4. The server api is validating the request and does the action.
5. It then replies to the website and the site outputs the action result to the user.

 

Website side

 

The requests are in the Requests folder in the web project.

 

Every request extends the L2Request abstract class.

Here is what this class looks like:

 

See here that the requests have an API key (which you will need to change) and a request id.

The request id is used by the server api to figure out how it should process the request.

Any extra properties should be added to the extended class.

 

In order to create a new request you need to extend L2Request and give it a request id.

Here is an example.

 

As you can see the buy item request has some properies as well as a request id which can be seen in the base(9).

This is all you need to do to create a website request for the server.

 

Now if this request needs to return something more that a confirmation message (ie some data) then you also have to create a response class that extends L2Response.

 

BuyItemRequest doesn't need a special response so it just answers with a L2Response.

This is what the response model looks like:

 

I only have two response codes for now. 200 for status ok and 500 for any error (planning to extend that)

 

 

When the request is send from the website to the server it is being serialized to a json string and encrypted with AES256.

Because the encryption is symmetric it is very important that you change any encryption keys provided by default.

 

In order to send the request to the server you need to create a method signature in the IRequestService interface.

It must look like this:

 

All requests MUST return Task<L2Reponse> in the interface signature. If it needs to return something that extends response then we cast it.

 

Here you can see the implementation of the request functionality:

 

Requests have an extension method named SendPostRequest<T>. T is generic and is replaced by extended responses if needed.

The extension method will serialize he model send the request and return the gameserver response object.

Notice here that the method need to be async as we will await it. Async programming offers better performance in C# if done right.

 

Here is how the buy item endpoint looks like on the site.

 

Some key things:

The HttpPost attribute shows that this endpoint accepts post requests.

The Route attribute shows the url path of the request.

async Task allows for asynchronous handling of the request.

[FromBody] means that the framework will map the Form Body to a model automatically.

return Content returns a string. However i am currently replacing them with return Json to return an object for flexible responses.

 

The rest is pretty straightforward.

 

This is how the jquery code looks like for this request:

 

 

Server API side

 

The server is accepting requests from the site.

The requests are registered in the L2ACPRequests enum on the com.elfocrash.l2acp package.

 

Here it is:

 

They are being turned into an array and using the request id we map them and kick off the processing process.

 

All the requests in the server api extend L2ACPRequests (name inconsistency i know)

Overriding the setContent method allows for getting values from the json object.

Here is how:

 

Note here that if it is a string, a int or a whatever you need to get it accordingly.

Also note here that you NEED to have the same pascal case then you do get.("Something") as the model was serialized on the website.

 

Responses extend the L2ACPResponse model class.

You only need to extend it and now send it as it is if you need to return data other than a success message.

 

Here is what an extended response looks like:

 

Note the property naming. They MUST be pascal case as they will be mapped to a website model dynamically and C# is using pascal case.

 

 

This is the main idea around how L2ACP works.

If you have any more questions please let me know.

Keep in mind i was prototyping a lot making this so many things are not final but the workflow is.

 

Star and fork the projects on GitHub.

https://github.com/Elfocrash/L2ACP-Web

https://github.com/Elfocrash/L2ACP-api

 

Thanks.

Edited May 3, 2017 by .Elfocrash

[Solomun]

I guess proper product comes along with proper instructions...Thanks Elfo, keep it up :)

 

+1.