Documentation ¶
Overview ¶
Package profile allows the username, ID, skin and username history of Minecraft profiles to be retrieved by either username or ID. It is a binding for the public Mojang API described at: http://wiki.vg/Mojang_API
Since Mojang's API historically have been inconsistent on whether demo profiles are returned or not, to ensure consistency this package have been written never to return those.
Please note that the public Mojang API is request rate limited, so if you expect heavy usage you should cache the results. For more information on rate limits see the documentation for ErrTooManyRequests.
Example ¶
The following example shows how to retrieve and report all information about a Minecraft profile based on its username.
package main import ( "fmt" "log" "context" "github.com/PhilipBorgesen/minecraft/profile" ) func main() { ctx := context.TODO() // User to retrieve information about const username = "nergalic" // Retrieve basic information p, err := profile.Load(ctx, username) if err != nil { log.Fatalf("failed to load: %s", err) } // Get case-corrected username and ID name, id := p.Name, p.ID // Load previously associated usernames hist, err := p.LoadNameHistory(ctx, false) if err != nil { log.Fatalf("failed to load name history: %s", err) } // Load cape, skin and model type props, err := p.LoadProperties(ctx, false) if err != nil { log.Fatalf("failed to load properties: %s", err) } // Get model type, skin and cape model, skin, cape := props.Model, props.SkinURL, props.CapeURL // If profile has no custom skin if skin == "" { skin = "<NONE>" } // If profile has no cape if cape == "" { cape = "<NONE>" } // Report information fmt.Printf("INFORMATION FOR: %32s\n", username) fmt.Println("---------------------------------------------------------") fmt.Printf("CASE-CORRECTED USERNAME: %32s\n", name) fmt.Printf("ID: %32s\n", id) fmt.Printf("PRIOR NAMES: %32s\n", fmt.Sprint(hist)) fmt.Println() fmt.Printf("SKIN MODEL: %32s\n", model) fmt.Printf("SKIN URL: %32s\n", skin) fmt.Printf("CAPE URL: %32s\n", cape) }
Output: INFORMATION FOR: nergalic --------------------------------------------------------- CASE-CORRECTED USERNAME: Nergalic ID: 087cc153c3434ff7ac497de1569affa1 PRIOR NAMES: [GeneralSezuan] SKIN MODEL: Steve SKIN URL: http://textures.minecraft.net/texture/5b40f251f7c8db60943495db6bf54353102d6cad20d2299d5f973f36b4f3677e CAPE URL: <NONE>
Index ¶
- Constants
- Variables
- type ErrMaxSizeExceeded
- type Model
- type PastName
- type Profile
- func Load(ctx context.Context, username string) (p *Profile, err error)
- func LoadAtTime(ctx context.Context, username string, tm time.Time) (p *Profile, err error)
- func LoadByID(ctx context.Context, id string) (p *Profile, err error)
- func LoadMany(ctx context.Context, username ...string) (ps []*Profile, err error)
- func LoadWithNameHistory(ctx context.Context, id string) (p *Profile, err error)
- func LoadWithProperties(ctx context.Context, id string) (p *Profile, err error)
- type Properties
Examples ¶
Constants ¶
const LoadManyMaxSize int = 100
The maximum number of profiles which may be requested at once using LoadMany. If more are requested, the request may fail with a ErrMaxSizeExceeded error.
Variables ¶
var ( ErrNoCape = errors.New("profile has no cape") ErrNoSuchProfile = errors.New("no such profile") // ErrTooManyRequests is returned when the client has exceeded its // server communication rate limit. At the time of writing, the load // operations have a shared rate limit of 600 requests per 10 minutes. // // Note that the rate limit for reading profile properties is much // stricter: For each profile, profile properties may only be requested // once per minute. ErrTooManyRequests = errors.New("request rate limit exceeded") )
Functions ¶
This section is empty.
Types ¶
type ErrMaxSizeExceeded ¶
type ErrMaxSizeExceeded struct { // The number of profiles which were requested Size int }
An ErrMaxSizeExceeded error is returned when LoadMany is requested to load more than LoadManyMaxSize profiles at once.
func (ErrMaxSizeExceeded) Error ¶
func (e ErrMaxSizeExceeded) Error() string
type PastName ¶
type PastName struct { // A username used by the profile in the past. Name string // The time instant the profile stopped using Name as username. // Prior past usernames may be consulted to determine when this // username was taken into use. A zero value means that the time // is unknown. Until time.Time // contains filtered or unexported fields }
PastName represents one of a profile's past usernames. PastName values should be used as map or database keys with caution as they contain a time.Time field. For the same reasons, do not use == with PastName values; use Equal instead.
type Profile ¶
type Profile struct { // Universally unique profile ID. ID string // Currently associated username. Name string // Past usernames incl. time of change, previous username first, original // username last. Unless explicitly loaded, NameHistory may be nil. NameHistory []PastName // Skin, model and cape used by the profile. // Nil unless Properties explicitly has been loaded. Properties *Properties // contains filtered or unexported fields }
Profile represents the profile of a Minecraft user account.
func Load ¶
Load fetches the profile currently associated with username. ctx must be non-nil. If no profile currently is associated with username, Load returns ErrNoSuchProfile. If an error is returned, p will be nil.
func LoadAtTime ¶
LoadAtTime fetches the profile associated with username at the specified instant of time. ctx must be non-nil. If no profile was associated with username at the specified instant of time, LoadAtTime returns ErrNoSuchProfile. If an error is returned, p will be nil.
func LoadByID ¶
LoadByID fetches the profile identified by id. ctx must be non-nil. If no profile is identified by id, LoadByID returns ErrNoSuchProfile. If an error is returned, p will be nil.
func LoadMany ¶
LoadMany fetches multiple profiles by their currently associated usernames. Usernames associated with no profile are ignored and absent from the returned results. Duplicate usernames are only returned once, and ps will be nil if an error occurs. ctx must be non-nil.
NB! Only a maximum of LoadManyMaxSize profiles may be fetched at once. If more are attempted loaded in the same operation, an ErrMaxSizeExceeded error occurs.
func LoadWithNameHistory ¶
LoadNameHistory fetches the profile identified by id, incl. its name history. ctx must be non-nil. If no profile is identified by id, LoadWithNameHistory returns ErrNoSuchProfile. If an error is returned, p will be nil.
func LoadWithProperties ¶
LoadWithProperties fetches the profile identified by a ID, incl. its properties. ctx must be non-nil. If no profile is identified by id, LoadWithProperties returns ErrNoSuchProfile. If an error is returned, p will be nil.
NB! For each profile, profile properties may only be requested once per minute.
func (*Profile) LoadNameHistory ¶
LoadNameHistory loads and returns p.NameHistory, which contains the profile's past usernames. If force is true, p.NameHistory will be loaded anew from the Mojang servers even though it already is present. If force is false, p.NameHistory will only be loaded if nil.
ctx must be non-nil and p.ID must be set. When properties are loaded, p.Name will also be updated if it has changed.
No matter whether the loading succeeds or not, p.NameHistory will be returned as hist, which thus only will be nil if the loading fails and p.NameHistory was nil beforehand.
A profile which was loaded by LoadWithNameHistory has p.NameHistory preloaded.
func (*Profile) LoadProperties ¶
LoadProperties loads and returns p.Properties, which contains the profile's skin, cape and model. If force is true, p.Properties will be loaded anew from the Mojang servers even though it already is present. If force is false, p.Properties will only be loaded if nil.
ctx must be non-nil and p.ID must be set. When properties are loaded, p.Name will also be updated if it has changed.
No matter whether the loading succeeds or not, p.Properties will be returned as ps, which thus only will be nil if the loading fails and p.Properties was nil beforehand.
A profile which was loaded by LoadWithProperties has p.Properties preloaded.
NB! For each profile, profile properties may only be requested once per minute.
type Properties ¶
type Properties struct { // URL to the profile's custom skin texture. If SkinURL is the empty // string, no skin texture has been set and the profile uses the // default skin for Model. SkinURL string // URL to the profile's cape texture. If CapeURL is the empty string, // no cape is associated with the profile. CapeURL string // The player model type used by the profile. If no model explicitly // has been set for the profile, a default Model will be determined // from the profile ID. Model Model // contains filtered or unexported fields }
Properties contains additional information associated with a Profile.
func (*Properties) CapeReader ¶
func (p *Properties) CapeReader(ctx context.Context) (io.ReadCloser, error)
SkinReader is a convenience method for retrieving the cape texture at p.CapeURL. ctx must be non-nil. If p.CapeURL is empty, ErrNoCape is returned as error.
It is the client's responsibility to close the ReadCloser. When an error is returned, ReadCloser is nil.
func (*Properties) SkinReader ¶
func (p *Properties) SkinReader(ctx context.Context) (io.ReadCloser, error)
SkinReader is a convenience method for retrieving the skin texture at p.SkinURL. If p.SkinURL is empty, the default texture for p.Model is retrieved instead. ctx must be non-nil.
It is the client's responsibility to close the ReadCloser. When an error is returned, ReadCloser is nil.